@agentuity/auth 0.0.108 → 0.0.110

package/src/agentuity/types.ts

@@ -0,0 +1,201 @@
+/**
+ * Auth types for @agentuity/auth.
+ *
+ * @module agentuity/types
+ */
+
+import type { Session as BetterAuthSession, User as BetterAuthUser } from 'better-auth';
+import type { AgentuityAuth } from '../types';
+
+// =============================================================================
+// Canonical User/Session Types
+// =============================================================================
+
+/**
+ * Canonical authenticated user type for Agentuity Auth.
+ *
+ * This is an alias for BetterAuth's `User` type and represents the shape of
+ * the `user` object you receive from:
+ *
+ * - `AuthInterface#getUser()` / `c.var.auth.getUser()` on the server
+ * - `c.var.user` in Hono route handlers
+ * - React hooks and context (`useAuth().user`) in `@agentuity/auth/react`
+ *
+ * Common fields include:
+ * - `id` – Stable user identifier
+ * - `email` – Primary email address
+ * - `name` – Display name
+ * - `image` – Avatar URL (if configured)
+ * - `createdAt` / `updatedAt` – Timestamps
+ *
+ * The exact fields are defined by BetterAuth and may be extended by plugins.
+ *
+ * @remarks
+ * Prefer using this `AuthUser` alias instead of referring to BetterAuth's
+ * `User` type directly so your code stays aligned with Agentuity's auth
+ * abstractions.
+ */
+export type AuthUser = BetterAuthUser;
+
+/**
+ * Auth session type.
+ * Extends BetterAuth's Session with organization plugin fields.
+ */
+export type AuthSession = BetterAuthSession & {
+	/** Active organization ID from the organization plugin */
+	activeOrganizationId?: string;
+};
+
+/**
+ * Auth context containing user, session, and org data.
+ * This is the full auth context available on AgentContext.auth and c.var.auth.
+ * Session may be null for API key authentication.
+ */
+export interface AuthContext<TUser = AuthUser, TSession = AuthSession | null> {
+	user: TUser;
+	session: TSession;
+	org: AuthOrgContext | null;
+}
+
+/**
+ * Organization context from the organization plugin.
+ */
+export interface AuthOrgContext {
+	/** Organization ID */
+	id: string;
+	/** Organization slug (URL-friendly identifier) */
+	slug?: string | null;
+	/** Organization display name */
+	name?: string | null;
+	/** Member's role in this organization (e.g., 'owner', 'admin', 'member') */
+	role?: string | null;
+	/** Member ID for this user in this organization */
+	memberId?: string | null;
+	/** Organization metadata (if enabled) */
+	metadata?: unknown;
+}
+
+// =============================================================================
+// API Key Types
+// =============================================================================
+
+/**
+ * API key permissions format.
+ * Maps resource names to arrays of allowed actions.
+ *
+ * @example
+ * ```typescript
+ * const permissions: AuthApiKeyPermissions = {
+ *   project: ['read', 'write'],
+ *   user: ['read'],
+ *   admin: ['*'], // wildcard - all actions
+ * };
+ * ```
+ */
+export type AuthApiKeyPermissions = Record<string, string[]>;
+
+/**
+ * API key context when request is authenticated via API key.
+ */
+export interface AuthApiKeyContext {
+	/** API key ID */
+	id: string;
+	/** Display name of the API key */
+	name?: string | null;
+	/** Permissions associated with this API key */
+	permissions: AuthApiKeyPermissions;
+	/** User ID the API key belongs to */
+	userId?: string | null;
+}
+
+/**
+ * Authentication method used for the current request.
+ */
+export type AuthMethod = 'session' | 'api-key' | 'bearer';
+
+// =============================================================================
+// Extended Auth Interface
+// =============================================================================
+
+/**
+ * Organization helpers available on the auth context.
+ */
+export interface AuthOrgHelpers {
+	/** Active organization context if available, null otherwise */
+	org: AuthOrgContext | null;
+
+	/** Returns active org or null (never throws) */
+	getOrg(): Promise<AuthOrgContext | null>;
+
+	/** Convenience accessor for the member's role on the active org */
+	getOrgRole(): Promise<string | null>;
+
+	/** True if the current member's role is one of the provided roles */
+	hasOrgRole(...roles: string[]): Promise<boolean>;
+}
+
+/**
+ * API key helpers available on the auth context.
+ */
+export interface AuthApiKeyHelpers {
+	/** How this request was authenticated */
+	authMethod: AuthMethod;
+
+	/** API key context when request is authenticated via API key, null otherwise */
+	apiKey: AuthApiKeyContext | null;
+
+	/**
+	 * Check if the API key has the required permissions.
+	 * All specified actions must be present for the resource.
+	 * Supports '*' wildcard which matches any action.
+	 *
+	 * @param resource - The resource to check (e.g., 'project', 'user')
+	 * @param actions - Actions required (e.g., 'read', 'write')
+	 * @returns true if all actions are permitted, false otherwise
+	 *
+	 * @example
+	 * ```typescript
+	 * // Check for specific permission
+	 * if (c.var.auth.hasPermission('project', 'write')) { ... }
+	 *
+	 * // Check for multiple permissions (all required)
+	 * if (c.var.auth.hasPermission('project', 'read', 'write')) { ... }
+	 * ```
+	 */
+	hasPermission(resource: string, ...actions: string[]): boolean;
+}
+
+/**
+ * Full authentication interface available on `c.var.auth` and `ctx.auth`.
+ *
+ * This is the primary interface you'll use to access authentication data
+ * in your route handlers and agents. It provides:
+ *
+ * - User data via `getUser()`
+ * - Organization helpers via `getOrg()`, `getOrgRole()`, `hasOrgRole()`
+ * - API key helpers via `apiKey`, `hasPermission()`
+ * - Token access via `getToken()`
+ *
+ * @example Route handler
+ * ```typescript
+ * app.get('/api/profile', async (c) => {
+ *   const user = await c.var.auth.getUser();
+ *   const org = await c.var.auth.getOrg();
+ *   return c.json({ user, org });
+ * });
+ * ```
+ *
+ * @example Agent handler
+ * ```typescript
+ * handler: async (ctx, input) => {
+ *   if (!ctx.auth) return { error: 'Unauthorized' };
+ *   const user = await ctx.auth.getUser();
+ *   return { message: `Hello, ${user.email}!` };
+ * }
+ * ```
+ *
+ * @typeParam TUser - User type (defaults to AuthUser)
+ */
+export type AuthInterface<TUser = AuthUser> = AgentuityAuth<TUser, AuthContext> &
+	AuthOrgHelpers &
+	AuthApiKeyHelpers;

package/src/index.ts

@@ -1,18 +1,86 @@
 /**
- * @agentuity/auth - Authentication helpers for identity providers
+ * @agentuity/auth - Authentication for Agentuity projects
  *
- * Currently supports Clerk, with more providers coming soon.
+ * Provides first-class authentication powered by BetterAuth.
  *
- * @example Clerk Integration
+ * This is the server-only entry point. For React components, import from '@agentuity/auth/react'.
+ *
+ * @example Server-side setup
  * ```typescript
- * // Client-side (React)
- * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ * import { createAuth, createSessionMiddleware, mountAuthRoutes } from '@agentuity/auth';
+ *
+ * const auth = createAuth({
+ *   connectionString: process.env.DATABASE_URL,
+ * });
+ *
+ * api.on(['GET', 'POST'], '/api/auth/*', mountAuthRoutes(auth));
+ * api.use('/api/*', createSessionMiddleware(auth));
+ * ```
+ *
+ * @example Client-side setup
+ * ```tsx
+ * import { createAuthClient, AuthProvider } from '@agentuity/auth/react';
+ *
+ * const authClient = createAuthClient();
  *
- * // Server-side (Hono)
- * import { createMiddleware } from '@agentuity/auth/clerk';
+ * <AgentuityProvider>
+ *   <AuthProvider authClient={authClient}>
+ *     <App />
+ *   </AuthProvider>
+ * </AgentuityProvider>
  * ```
  *
  * @module @agentuity/auth
  */
 
-export type { AgentuityAuthUser, AgentuityAuth } from './types';
+// =============================================================================
+// Config
+// =============================================================================
+
+export { createAuth, getDefaultPlugins, DEFAULT_API_KEY_OPTIONS } from './agentuity/config';
+export type {
+	AuthOptions,
+	AuthInstance,
+	AuthBase,
+	ApiKeyPluginOptions,
+	OrganizationApiMethods,
+	ApiKeyApiMethods,
+	JwtApiMethods,
+	DefaultPluginApiMethods,
+} from './agentuity/config';
+
+// =============================================================================
+// Server (Hono middleware and handlers)
+// =============================================================================
+
+export {
+	createSessionMiddleware,
+	createApiKeyMiddleware,
+	mountAuthRoutes,
+} from './agentuity/server';
+export type {
+	AuthMiddlewareOptions,
+	ApiKeyMiddlewareOptions,
+	AuthEnv,
+	OtelSpansConfig,
+	MountAuthRoutesOptions,
+} from './agentuity/server';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+	AuthContext,
+	AuthOrgContext,
+	AuthApiKeyContext,
+	AuthApiKeyPermissions,
+	AuthMethod,
+	AuthOrgHelpers,
+	AuthApiKeyHelpers,
+	AuthInterface,
+	AuthUser,
+	AuthSession,
+} from './agentuity/types';
+
+export type { AgentuityAuth } from './types';

package/src/schema.ts

@@ -0,0 +1,270 @@
+/**
+ * Agentuity Auth Drizzle schema.
+ *
+ * Provides type-safe Drizzle table definitions for BetterAuth with Agentuity's
+ * default plugins (organization, JWT, bearer, API key).
+ *
+ * @module agentuity/schema
+ *
+ * @example Merge with your app schema
+ * ```typescript
+ * import * as authSchema from '@agentuity/auth/schema';
+ * import { drizzle } from 'drizzle-orm/bun-sql';
+ *
+ * const schema = { ...authSchema, ...myAppSchema };
+ * const db = drizzle(connectionString, { schema });
+ * ```
+ */
+
+import { pgTable, text, boolean, timestamp, integer, index } from 'drizzle-orm/pg-core';
+import { relations } from 'drizzle-orm';
+
+// =============================================================================
+// BetterAuth Core Tables
+// =============================================================================
+
+export const user = pgTable('user', {
+	id: text('id').primaryKey(),
+	name: text('name').notNull(),
+	email: text('email').notNull().unique(),
+	emailVerified: boolean('emailVerified').notNull().default(false),
+	image: text('image'),
+	createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+	updatedAt: timestamp('updatedAt', { withTimezone: true }).defaultNow().notNull(),
+});
+
+export const session = pgTable(
+	'session',
+	{
+		id: text('id').primaryKey(),
+		expiresAt: timestamp('expiresAt', { withTimezone: true }).notNull(),
+		token: text('token').notNull().unique(),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+		updatedAt: timestamp('updatedAt', { withTimezone: true }).notNull(),
+		ipAddress: text('ipAddress'),
+		userAgent: text('userAgent'),
+		userId: text('userId')
+			.notNull()
+			.references(() => user.id, { onDelete: 'cascade' }),
+		activeOrganizationId: text('activeOrganizationId'),
+	},
+	(table) => [index('session_userId_idx').on(table.userId)]
+);
+
+export const account = pgTable(
+	'account',
+	{
+		id: text('id').primaryKey(),
+		accountId: text('accountId').notNull(),
+		providerId: text('providerId').notNull(),
+		userId: text('userId')
+			.notNull()
+			.references(() => user.id, { onDelete: 'cascade' }),
+		accessToken: text('accessToken'),
+		refreshToken: text('refreshToken'),
+		idToken: text('idToken'),
+		accessTokenExpiresAt: timestamp('accessTokenExpiresAt', { withTimezone: true }),
+		refreshTokenExpiresAt: timestamp('refreshTokenExpiresAt', { withTimezone: true }),
+		scope: text('scope'),
+		password: text('password'),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+		updatedAt: timestamp('updatedAt', { withTimezone: true }).notNull(),
+	},
+	(table) => [index('account_userId_idx').on(table.userId)]
+);
+
+export const verification = pgTable(
+	'verification',
+	{
+		id: text('id').primaryKey(),
+		identifier: text('identifier').notNull(),
+		value: text('value').notNull(),
+		expiresAt: timestamp('expiresAt', { withTimezone: true }).notNull(),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+		updatedAt: timestamp('updatedAt', { withTimezone: true }).defaultNow().notNull(),
+	},
+	(table) => [index('verification_identifier_idx').on(table.identifier)]
+);
+
+// =============================================================================
+// Organization Plugin Tables
+// =============================================================================
+
+export const organization = pgTable('organization', {
+	id: text('id').primaryKey(),
+	name: text('name').notNull(),
+	slug: text('slug').notNull().unique(),
+	logo: text('logo'),
+	createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+	metadata: text('metadata'),
+});
+
+export const member = pgTable(
+	'member',
+	{
+		id: text('id').primaryKey(),
+		organizationId: text('organizationId')
+			.notNull()
+			.references(() => organization.id, { onDelete: 'cascade' }),
+		userId: text('userId')
+			.notNull()
+			.references(() => user.id, { onDelete: 'cascade' }),
+		role: text('role').notNull(),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+	},
+	(table) => [
+		index('member_organizationId_idx').on(table.organizationId),
+		index('member_userId_idx').on(table.userId),
+	]
+);
+
+export const invitation = pgTable(
+	'invitation',
+	{
+		id: text('id').primaryKey(),
+		organizationId: text('organizationId')
+			.notNull()
+			.references(() => organization.id, { onDelete: 'cascade' }),
+		email: text('email').notNull(),
+		role: text('role'),
+		status: text('status').notNull(),
+		expiresAt: timestamp('expiresAt', { withTimezone: true }).notNull(),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+		inviterId: text('inviterId')
+			.notNull()
+			.references(() => user.id, { onDelete: 'cascade' }),
+	},
+	(table) => [
+		index('invitation_organizationId_idx').on(table.organizationId),
+		index('invitation_email_idx').on(table.email),
+	]
+);
+
+// =============================================================================
+// JWT Plugin Table
+// =============================================================================
+
+export const jwks = pgTable('jwks', {
+	id: text('id').primaryKey(),
+	publicKey: text('publicKey').notNull(),
+	privateKey: text('privateKey').notNull(),
+	createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+	expiresAt: timestamp('expiresAt', { withTimezone: true }),
+});
+
+// =============================================================================
+// API Key Plugin Table
+// =============================================================================
+
+export const apikey = pgTable(
+	'apikey',
+	{
+		id: text('id').primaryKey(),
+		name: text('name'),
+		start: text('start'),
+		prefix: text('prefix'),
+		key: text('key').notNull(),
+		userId: text('userId')
+			.notNull()
+			.references(() => user.id, { onDelete: 'cascade' }),
+		refillInterval: integer('refillInterval'),
+		refillAmount: integer('refillAmount'),
+		lastRefillAt: timestamp('lastRefillAt', { withTimezone: true }),
+		enabled: boolean('enabled').notNull().default(true),
+		rateLimitEnabled: boolean('rateLimitEnabled').notNull().default(true),
+		rateLimitTimeWindow: integer('rateLimitTimeWindow').notNull().default(86400000),
+		rateLimitMax: integer('rateLimitMax').notNull().default(10),
+		requestCount: integer('requestCount').notNull().default(0),
+		remaining: integer('remaining'),
+		lastRequest: timestamp('lastRequest', { withTimezone: true }),
+		expiresAt: timestamp('expiresAt', { withTimezone: true }),
+		createdAt: timestamp('createdAt', { withTimezone: true }).defaultNow().notNull(),
+		updatedAt: timestamp('updatedAt', { withTimezone: true }).defaultNow().notNull(),
+		permissions: text('permissions'),
+		metadata: text('metadata'),
+	},
+	(table) => [index('apikey_userId_idx').on(table.userId), index('apikey_key_idx').on(table.key)]
+);
+
+// =============================================================================
+// Relations (required for BetterAuth join optimization)
+// =============================================================================
+
+export const userRelations = relations(user, ({ many }) => ({
+	sessions: many(session),
+	accounts: many(account),
+	members: many(member),
+	apikeys: many(apikey),
+	invitations: many(invitation),
+}));
+
+export const sessionRelations = relations(session, ({ one }) => ({
+	user: one(user, {
+		fields: [session.userId],
+		references: [user.id],
+	}),
+}));
+
+export const accountRelations = relations(account, ({ one }) => ({
+	user: one(user, {
+		fields: [account.userId],
+		references: [user.id],
+	}),
+}));
+
+export const organizationRelations = relations(organization, ({ many }) => ({
+	members: many(member),
+	invitations: many(invitation),
+}));
+
+export const memberRelations = relations(member, ({ one }) => ({
+	organization: one(organization, {
+		fields: [member.organizationId],
+		references: [organization.id],
+	}),
+	user: one(user, {
+		fields: [member.userId],
+		references: [user.id],
+	}),
+}));
+
+export const invitationRelations = relations(invitation, ({ one }) => ({
+	organization: one(organization, {
+		fields: [invitation.organizationId],
+		references: [organization.id],
+	}),
+	inviter: one(user, {
+		fields: [invitation.inviterId],
+		references: [user.id],
+	}),
+}));
+
+export const apikeyRelations = relations(apikey, ({ one }) => ({
+	user: one(user, {
+		fields: [apikey.userId],
+		references: [user.id],
+	}),
+}));
+
+// =============================================================================
+// Combined schema export (for easy spreading into app schema)
+// =============================================================================
+
+export const authSchema = {
+	user,
+	session,
+	account,
+	verification,
+	organization,
+	member,
+	invitation,
+	jwks,
+	apikey,
+	userRelations,
+	sessionRelations,
+	accountRelations,
+	organizationRelations,
+	memberRelations,
+	invitationRelations,
+	apikeyRelations,
+};

package/src/types.ts

@@ -1,38 +1,30 @@
 /**
- * Core authentication types shared across all providers.
+ * Core authentication types for Agentuity Auth.
  *
  * @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.
+ *
+ * This type is intentionally provider-agnostic. For AgentuityAuth-based
+ * projects, prefer {@link AuthInterface} from `./agentuity/types`,
+ * which binds:
+ * - `TUser` to {@link AuthUser}
+ * - `TRaw` to {@link AuthContext}
+ *
+ * @typeParam TUser - Domain user type (e.g. AuthUser in AgentuityAuth projects).
+ * @typeParam TRaw - Underlying auth context (e.g. AuthContext, JWT payload, or session object).
+ *
+ * @see {@link AuthInterface} for the full AgentuityAuth-specific interface with org and API key helpers.
  */
 export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
 	/** Get the authenticated user, throws if not authenticated */
-	getUser(): Promise<AgentuityAuthUser<TUser>>;
+	getUser(): Promise<TUser>;
 
 	/** Get the raw JWT token */
 	getToken(): Promise<string | null>;
 
-	/** Raw provider-specific auth object (e.g., JWT payload, session) */
+	/** Raw provider-specific auth object or auth context (e.g. AuthContext, JWT payload, session) */
 	raw: TRaw;
 }