@agentuity/auth 0.0.109 → 0.0.111

package/README.md

@@ -1,15 +1,16 @@
 # @agentuity/auth
 
-Drop-in authentication helpers for popular identity providers (Clerk, WorkOS, Auth0, Better Auth, etc.).
+First-class authentication for Agentuity projects, powered by [BetterAuth](https://better-auth.com).
 
 ## Features
 
-- ✅ **Zero Configuration**: Drop-in components that work out of the box
-- ✅ **Provider Agnostic**: Generic interfaces allow routes to be provider-independent
-- ✅ **Tree Shakeable**: Import only the providers you use (`@agentuity/auth/clerk`)
-- ✅ **Type Safe**: Full TypeScript support with proper type inference
-- ✅ **Automatic Token Injection**: Seamless integration with `useAPI` and `useWebsocket`
-- ✅ **Server Validation**: Easy middleware for token validation and user context
+- ✅ **Zero Configuration**: Works out of the box with just a database connection
+- ✅ **Native Integration**: `ctx.auth` available on AgentContext and Hono routes
+- ✅ **Organizations**: Multi-tenancy with roles and permissions
+- ✅ **API Keys**: Programmatic access with fine-grained permissions
+- ✅ **JWT Tokens**: Stateless auth for API calls
+- ✅ **Drizzle Schema**: Type-safe database schema with migrations
+- ✅ **React Hooks**: `useAuth()` for client-side auth state
 
 ## Installation
 
@@ -17,354 +18,376 @@ Drop-in authentication helpers for popular identity providers (Clerk, WorkOS, Au
 bun add @agentuity/auth
 ```
 
-## Supported Providers
+## Quick Start
 
-- **Clerk** - `@agentuity/auth/clerk`
-- WorkOS - Coming soon
-- Auth0 - Coming soon
-- Better Auth - Coming soon
+### 1. Setup with CLI
 
-## Quick Start
+```bash
+agentuity project auth init
+```
 
-### Clerk Integration
+This will:
 
-#### 1. Install Clerk
+- Install required dependencies
+- Generate `src/auth.ts` with default configuration
+- Set up environment variables
+
+### 2. Configure Database
 
 ```bash
-bun add @clerk/clerk-react @clerk/backend
+# Create a database and get connection URL
+agentuity cloud database create --region use
+
+# Run auth migrations
+agentuity project auth setup
 ```
 
-#### 2. Client Setup (React)
+### 3. Server Setup (Hono)
 
-```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { ClerkProvider, useAuth } from '@clerk/clerk-react';
-import { AgentuityProvider } from '@agentuity/react';
-import { AgentuityClerk } from '@agentuity/auth/clerk';
-import { App } from './App';
+```typescript
+// src/auth.ts
+import { createAuth, createSessionMiddleware, mountAuthRoutes } from '@agentuity/auth';
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-	<React.StrictMode>
-		<ClerkProvider publishableKey={process.env.AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY!}>
-			<AgentuityProvider>
-				<AgentuityClerk useAuth={useAuth}>
-					<App />
-				</AgentuityClerk>
-			</AgentuityProvider>
-		</ClerkProvider>
-	</React.StrictMode>
-);
-```
+export const auth = createAuth({
+	connectionString: process.env.DATABASE_URL,
+	// Uses AGENTUITY_AUTH_SECRET env var by default
+});
 
-#### 3. Server Setup (Hono)
+export const authMiddleware = createSessionMiddleware(auth);
+export const optionalAuthMiddleware = createSessionMiddleware(auth, { optional: true });
+```
 
 ```typescript
+// src/api/index.ts
 import { createRouter } from '@agentuity/runtime';
-import { createMiddleware } from '@agentuity/auth/clerk';
+import { auth, authMiddleware } from '../auth';
+import { mountAuthRoutes } from '@agentuity/auth';
+
+const api = createRouter();
 
-const router = createRouter();
+// Mount auth routes (sign-in, sign-up, sign-out, session, etc.)
+api.on(['GET', 'POST'], '/api/auth/*', mountAuthRoutes(auth));
 
-// Protected route
-router.get('/profile', createMiddleware(), async (c) => {
+// Protect API routes
+api.use('/api/*', authMiddleware);
+
+api.get('/api/me', async (c) => {
 	const user = await c.var.auth.getUser();
-	return c.json({
-		id: user.id,
-		name: user.name,
-		email: user.email,
-	});
+	return c.json({ id: user.id, email: user.email });
 });
 
-export default router;
+export default api;
 ```
 
-#### 4. Environment Variables
-
-Create a `.env` file:
+### 4. Client Setup (React)
 
-```env
-# Client-side (bundled into frontend)
-AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+```tsx
+// src/web/auth-client.ts
+import { createAuthClient } from '@agentuity/auth/react';
 
-# Server-side (kept secret)
-CLERK_SECRET_KEY=sk_test_...
+export const authClient = createAuthClient();
+export const { signIn, signUp, signOut, useSession } = authClient;
 ```
 
-Get your keys from [Clerk Dashboard](https://dashboard.clerk.com).
+```tsx
+// src/web/frontend.tsx
+import { AgentuityProvider } from '@agentuity/react';
+import { createAuthClient, AuthProvider } from '@agentuity/auth/react';
+import { App } from './App';
 
-## Usage
+const authClient = createAuthClient();
 
-### Client Side
+<AgentuityProvider>
+	<AuthProvider authClient={authClient}>
+		<App />
+	</AuthProvider>
+</AgentuityProvider>;
+```
 
-Once you wrap your app with `AgentuityClerk`, all `useAPI` and `useWebsocket` calls automatically include the auth token:
+### 5. Environment Variables
 
-```tsx
-import { useAPI, useAuth } from '@agentuity/react';
+```env
+# Database connection
+DATABASE_URL=postgresql://user:pass@host:5432/dbname
 
-function MyComponent() {
-	const { isAuthenticated, authLoading } = useAuth();
-	const { data, invoke } = useAPI('POST /api/users');
+# Auth secret (generate with: openssl rand -hex 32)
+AGENTUITY_AUTH_SECRET=your-secret-here
+```
 
-	if (authLoading) {
-		return <div>Loading...</div>;
-	}
+## Usage
 
-	if (!isAuthenticated) {
-		return <div>Please sign in</div>;
-	}
+### Agent Access
 
-	return <button onClick={() => invoke({ name: 'Alice' })}>Create User</button>;
-}
-```
+Auth is native on AgentContext - no wrappers needed:
 
-### Server Side
+```typescript
+import { createAgent } from '@agentuity/runtime';
 
-#### Basic Protection
+export default createAgent('my-agent', {
+	handler: async (ctx, input) => {
+		// ctx.auth is available when using auth middleware
+		if (!ctx.auth) {
+			return { error: 'Please sign in' };
+		}
 
-```typescript
-import { createMiddleware } from '@agentuity/auth/clerk';
+		const user = await ctx.auth.getUser();
+		const org = await ctx.auth.getOrg();
 
-// Protect a single route
-router.post('/admin', createMiddleware(), async (c) => {
-	const user = await c.var.auth.getUser();
-	return c.json({ admin: true, userId: user.id });
+		// Check organization roles
+		if (org && (await ctx.auth.hasOrgRole('admin'))) {
+			// Admin-only logic
+		}
+
+		return { userId: user.id, orgId: org?.id };
+	},
 });
 ```
 
-#### Global Middleware
+### Hono Routes
 
 ```typescript
-// Protect all routes under /api
-router.use('/api/*', createMiddleware());
+import { createSessionMiddleware, createApiKeyMiddleware } from '@agentuity/auth';
 
-router.get('/api/profile', async (c) => {
+// Session-based auth
+api.get('/api/profile', authMiddleware, async (c) => {
 	const user = await c.var.auth.getUser();
 	return c.json({ email: user.email });
 });
+
+// API key auth
+api.use('/api/v1/*', createApiKeyMiddleware(auth));
+
+api.get('/api/v1/data', async (c) => {
+	// Check API key permissions
+	if (!c.var.auth.hasPermission('data', 'read')) {
+		return c.json({ error: 'Forbidden' }, 403);
+	}
+	return c.json({ data: '...' });
+});
 ```
 
-#### Access Provider-Specific Data
+### React Components
 
-```typescript
-router.get('/profile', createMiddleware(), async (c) => {
-	const user = await c.var.auth.getUser();
+```tsx
+import { useAuth } from '@agentuity/react';
+import { useAuth } from '@agentuity/auth/react';
 
-	// Access generic fields
-	console.log(user.id, user.email, user.name);
+function Profile() {
+	// Basic auth state from @agentuity/react
+	const { isAuthenticated, authLoading } = useAuth();
 
-	// Access Clerk-specific fields (fully typed)
-	const clerkUser = user.raw; // Type: User from @clerk/backend
-	console.log(clerkUser.imageUrl);
-	console.log(clerkUser.publicMetadata);
+	// Full auth context from @agentuity/auth
+	const { user, isPending } = useAuth();
 
-	// Access JWT payload
-	const payload = c.var.auth.raw; // Type: ClerkJWTPayload
-	console.log(payload.sub);
+	if (authLoading || isPending) return <div>Loading...</div>;
+	if (!isAuthenticated) return <div>Please sign in</div>;
 
-	return c.json({ user });
-});
+	return <div>Welcome, {user?.name}!</div>;
+}
 ```
 
-#### Custom Middleware Options
+## Database Configuration
+
+### Option A: Connection String (Simplest)
 
 ```typescript
-import { createMiddleware } from '@agentuity/auth/clerk';
-
-router.use(
-	'/api/*',
-	createMiddleware({
-		secretKey: 'custom-secret',
-		publishableKey: 'custom-publishable',
-		getToken: (authHeader) => authHeader.replace('Custom ', ''),
-	})
-);
+import { createAuth } from '@agentuity/auth';
+
+export const auth = createAuth({
+	connectionString: process.env.DATABASE_URL,
+});
 ```
 
-## API Reference
+### Option B: Bring Your Own Drizzle
 
-### Client Components
+Merge auth schema with your app schema:
 
-#### `AgentuityClerk`
+```typescript
+import { drizzle } from 'drizzle-orm/bun-sql';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import * as authSchema from '@agentuity/auth/schema';
+import * as myAppSchema from './schema';
 
-React component that integrates Clerk with Agentuity context.
+const schema = { ...authSchema, ...myAppSchema };
+const db = drizzle(process.env.DATABASE_URL!, { schema });
 
-**Props:**
+export const auth = createAuth({
+	database: drizzleAdapter(db, { provider: 'pg', schema: authSchema }),
+});
+```
 
-- `useAuth: UseAuth` - Clerk's `useAuth` hook from `@clerk/clerk-react`
-- `children: React.ReactNode` - Your app components
-- `refreshInterval?: number` - Token refresh interval in ms (default: 60000)
+### Option C: Other Adapters
 
-**Example:**
+Use any BetterAuth-compatible adapter:
 
-```tsx
-<AgentuityClerk useAuth={useAuth} refreshInterval={30000}>
-	<App />
-</AgentuityClerk>
+```typescript
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+
+export const auth = createAuth({
+	database: prismaAdapter(new PrismaClient()),
+});
 ```
 
-### Server Middleware
+## API Reference
+
+### Server
 
-#### `createMiddleware(options?)`
+#### `createAuth(options)`
 
-Creates Hono middleware for Clerk authentication.
+Creates an auth instance with Agentuity defaults.
 
 **Options:**
 
-- `secretKey?: string` - Clerk secret key (defaults to `process.env.CLERK_SECRET_KEY`)
-- `publishableKey?: string` - Clerk publishable key (defaults to `process.env.AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY` or `process.env.CLERK_PUBLISHABLE_KEY`)
-- `getToken?: (authHeader: string) => string` - Custom token extractor
+- `connectionString?: string` - PostgreSQL connection URL (simplest path)
+- `database?: Adapter` - BetterAuth database adapter (for advanced use)
+- `secret?: string` - Auth secret (defaults to `AGENTUITY_AUTH_SECRET` env var)
+- `basePath?: string` - API path prefix (default: `/api/auth`)
+- `emailAndPassword?: { enabled: boolean }` - Email auth (default: `{ enabled: true }`)
+- `skipDefaultPlugins?: boolean` - Skip organization, JWT, bearer, API key plugins
+- `apiKey?: ApiKeyPluginOptions | false` - API key configuration
+- `plugins?: Plugin[]` - Additional BetterAuth plugins
 
-**Returns:** Hono `MiddlewareHandler`
+#### `createSessionMiddleware(auth, options?)`
 
-**Behavior:**
+Hono middleware for session-based auth.
 
-- Returns 401 if Authorization header is missing
-- Returns 401 if token is invalid
-- Sets `c.var.auth` with authenticated user context
+**Options:**
 
-### Context Hooks
+- `optional?: boolean` - If true, don't 401 on missing auth
+- `otelSpans?: { email?: boolean, orgName?: boolean }` - Control PII in spans
 
-#### `useAuth()`
+#### `createApiKeyMiddleware(auth, options?)`
 
-Hook to access authentication state (from `@agentuity/react`).
+Hono middleware for API key auth.
 
-**Returns:**
+**Options:**
 
-```typescript
-{
-  authHeader?: string | null;
-  authLoading?: boolean;
-  isAuthenticated: boolean; // Convenience: !authLoading && authHeader !== null
-  setAuthHeader?: (token: string | null) => void;
-  setAuthLoading?: (loading: boolean) => void;
-}
-```
+- `optional?: boolean` - If true, don't 401 on missing API key
+- `otelSpans?: { email?: boolean }` - Control PII in spans
 
-#### `useAgentuity()`
+#### `mountAuthRoutes(auth, options?)`
 
-Hook to access Agentuity context (non-auth properties only, from `@agentuity/react`).
+Handler for BetterAuth routes with cookie merging.
 
-**Returns:**
+**Options:**
 
-```typescript
-{
-	baseUrl: string;
-}
-```
+- `allowList?: string[]` - Headers to forward from auth responses
 
-### Types
+### Client
 
-#### `AgentuityAuthUser<T>`
+#### `createAuthClient(options?)`
 
-Generic authenticated user interface.
+Import from `@agentuity/auth/react`.
 
-```typescript
-interface AgentuityAuthUser<T = unknown> {
-	id: string;
-	name?: string;
-	email?: string;
-	raw: T; // Provider-specific user object
-}
-```
+**Options:**
 
-#### `AgentuityAuth<TUser, TRaw>`
+- `baseURL?: string` - API base URL (default: `window.location.origin`)
+- `basePath?: string` - Auth path prefix (default: `/api/auth`)
+- `skipDefaultPlugins?: boolean` - Skip organization and API key plugins
+- `plugins?: Plugin[]` - Additional client plugins
 
-Generic authentication interface exposed on Hono context.
+**Returns:** BetterAuth client with `signIn`, `signUp`, `signOut`, `useSession`, etc.
 
-```typescript
-interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
-	getUser(): Promise<AgentuityAuthUser<TUser>>;
-	getToken(): Promise<string | null>;
-	raw: TRaw; // Provider-specific auth object (e.g., JWT payload)
-}
-```
+#### `AuthProvider`
 
-## Templates
+React provider that bridges auth state to Agentuity context.
 
-Get started quickly with the Clerk template:
+```tsx
+import { AuthProvider } from '@agentuity/auth/react';
 
-```bash
-bunx agentuity create my-app --template clerk
-cd my-app
-cp .env.example .env
-# Add your Clerk keys to .env
-bun dev
+<AuthProvider authClient={authClient} refreshInterval={60000}>
+	{children}
+</AuthProvider>;
 ```
 
-## Security Best Practices
-
-1. **Never log tokens** - Avoid logging `authHeader` or JWT tokens
-2. **Use HTTPS in production** - Always use TLS for production deployments
-3. **Validate on every request** - Middleware validates tokens on each request
-4. **Keep secrets secret** - Never commit `.env` files or expose `CLERK_SECRET_KEY`
-5. **Use environment variables** - Store all keys in environment variables, not code
+#### `useAuth()`
 
-## Troubleshooting
+Hook for full auth context. Import from `@agentuity/auth/react`.
 
-### "Unauthorized" errors when signed in
+**Returns:**
 
-**Check:**
+- `user: AuthUser | null`
+- `isPending: boolean`
+- `error: Error | null`
+- `isAuthenticated: boolean`
+- `authClient: AuthClient`
 
-1. Authorization header is present in request (browser DevTools → Network tab)
-2. `CLERK_SECRET_KEY` is set in server environment
-3. Token is being fetched (check console for "Failed to get Clerk token")
+### Schema
 
-**Debug:**
+Import from `@agentuity/auth/schema`:
 
-```tsx
-const { authHeader, authLoading, isAuthenticated } = useAuth();
-console.log({ authHeader, authLoading, isAuthenticated });
+```typescript
+import { user, session, organization, apikey, authSchema } from '@agentuity/auth/schema';
 ```
 
-### "Clerk secret key is required" error
+**Tables:**
 
-Set `CLERK_SECRET_KEY` in your `.env` file:
+- `user` - User accounts
+- `session` - Active sessions
+- `account` - OAuth/credential accounts
+- `verification` - Email verification tokens
+- `organization` - Organizations
+- `member` - Organization memberships
+- `invitation` - Pending invitations
+- `jwks` - JWT signing keys
+- `apikey` - API keys
 
-```env
-CLERK_SECRET_KEY=sk_test_...
+**Combined:**
+
+- `authSchema` - All tables and relations for easy spreading
+
+### Types
+
+```typescript
+import type {
+	AuthUser,
+	AuthSession,
+	AuthContext,
+	AuthOrgContext,
+	AuthApiKeyContext,
+	AuthMethod,
+	AuthInterface,
+} from '@agentuity/auth';
 ```
 
-### Token not being sent in requests
+## CLI Commands
 
-Ensure `AgentuityClerk` is a **child** of `AgentuityProvider`:
+```bash
+# Initialize auth in a project
+agentuity project auth init
 
-```tsx
-// ✅ CORRECT
-<AgentuityProvider>
-  <AgentuityClerk useAuth={useAuth}>
-    <App />
-  </AgentuityClerk>
-</AgentuityProvider>
-
-// ❌ WRONG
-<AgentuityClerk useAuth={useAuth}>
-  <AgentuityProvider>
-    <App />
-  </AgentuityProvider>
-</AgentuityClerk>
+# Run database migrations
+agentuity project auth setup
+
+# Generate Drizzle schema
+agentuity project auth generate
+
+# Generate a secure secret
+agentuity project auth secret
 ```
 
-## Examples
+## Security Best Practices
+
+1. **Use HTTPS in production** - Always use TLS for deployments
+2. **Keep secrets secret** - Never commit `.env` files or expose `AGENTUITY_AUTH_SECRET`
+3. **Rotate secrets periodically** - Rotate `AGENTUITY_AUTH_SECRET` on a regular schedule
+4. **Control OTEL PII** - Use `otelSpans: { email: false }` to exclude sensitive data from telemetry
+5. **Validate permissions** - Always check `hasPermission()` for API key routes
 
-See the [Clerk template](../../templates/clerk/) for a complete working example with:
+## Templates
 
-- Sign-in/out UI
-- Protected routes
-- Public routes
-- Conditional rendering based on auth state
+Get started quickly:
 
-## Contributing
+```bash
+bunx agentuity create my-app --template agentuity-auth
+```
 
-This package follows the [Agentuity SDK contributing guidelines](../../AGENTS.md).
+## Third-Party Providers
 
-To add a new provider:
+Agentuity Auth is the recommended solution. For Clerk, Auth0, or other providers, see:
 
-1. Create `src/<provider>/` directory
-2. Implement `client.tsx` and `server.ts`
-3. Export from `src/<provider>/index.ts`
-4. Add export path to `package.json`
-5. Add peer dependencies
-6. Write tests in `test/<provider>-*.test.ts`
+- [Clerk Integration Guide](../../docs/recipes/clerk.md)
+- [Auth0 Integration Guide](../../docs/recipes/auth0.md)
 
 ## License