@agentuity/auth 0.1.7 → 0.1.9

package/src/agentuity/config.ts

@@ -1,401 +0,0 @@
-/**
- * Auth configuration for @agentuity/auth.
- *
- * Provides sensible defaults and wraps BetterAuth with Agentuity-specific helpers.
- *
- * @module agentuity/config
- */
-
-import { betterAuth, type BetterAuthOptions } from 'better-auth';
-import { drizzleAdapter } from 'better-auth/adapters/drizzle';
-import { organization, jwt, bearer, apiKey } from 'better-auth/plugins';
-import { drizzle } from 'drizzle-orm/bun-sql';
-import * as authSchema from '../schema';
-
-// Re-export plugin types for convenience
-export type {
-	Organization,
-	OrganizationMember,
-	OrganizationInvitation,
-	OrganizationApiMethods,
-	ApiKey,
-	ApiKeyPluginOptions,
-	ApiKeyApiMethods,
-	JwtApiMethods,
-	DefaultPluginApiMethods,
-} from './plugins';
-
-export { DEFAULT_API_KEY_OPTIONS } from './plugins';
-
-import type { ApiKeyPluginOptions, DefaultPluginApiMethods } from './plugins';
-import { DEFAULT_API_KEY_OPTIONS } from './plugins';
-
-/**
- * Type for BetterAuth trustedOrigins option.
- * Matches the signature expected by BetterAuthOptions.trustedOrigins.
- */
-type TrustedOrigins = string[] | ((request?: Request) => string[] | Promise<string[]>);
-
-// =============================================================================
-// Base Interface for Middleware
-// =============================================================================
-
-/**
- * Base interface for the auth instance used by middleware and route handlers.
- *
- * This interface defines the core authentication APIs that Agentuity middleware
- * relies on. It's designed to be stable and middleware-friendly while the full
- * auth instance provides additional type-safe APIs for your application code.
- *
- * @remarks
- * You typically don't interact with this interface directly. Instead, use
- * `createAuth()` to create an auth instance which implements this interface.
- *
- * @see {@link createAuth} - Create an auth instance
- * @see {@link createSessionMiddleware} - Session-based authentication middleware
- * @see {@link createApiKeyMiddleware} - API key authentication middleware
- */
-export interface AuthBase {
-	/**
-	 * HTTP request handler for auth routes.
-	 *
-	 * Handles all auth-related endpoints like sign-in, sign-up, sign-out,
-	 * password reset, OAuth callbacks, and session management.
-	 *
-	 * @param request - The incoming HTTP request
-	 * @returns Response for the auth endpoint
-	 */
-	handler: (request: Request) => Promise<Response>;
-
-	/**
-	 * Server-side API methods for authentication operations.
-	 *
-	 * These methods are used internally by middleware and can also be called
-	 * directly in your route handlers for custom authentication logic.
-	 */
-	api: {
-		/**
-		 * Get the current session from request headers.
-		 *
-		 * @param params - Object containing the request headers
-		 * @returns The session with user info, or null if not authenticated
-		 */
-		getSession: (params: { headers: Headers }) => Promise<{
-			user: { id: string; name?: string | null; email: string };
-			session: { id: string; userId: string; activeOrganizationId?: string };
-		} | null>;
-
-		/**
-		 * Get full organization details including members.
-		 *
-		 * @param params - Object containing the request headers
-		 * @returns Full organization details, or null if no active org
-		 */
-		getFullOrganization: (params: {
-			query?: {
-				organizationId?: string;
-				organizationSlug?: string;
-				membersLimit?: number;
-			};
-			headers?: Headers;
-		}) => Promise<{
-			id: string;
-			name?: string;
-			slug?: string;
-			members?: Array<{ userId: string; role: string; id?: string }>;
-		} | null>;
-
-		/**
-		 * Verify an API key and get its metadata.
-		 *
-		 * @param params - Object containing the API key to verify
-		 * @returns Validation result with key details if valid
-		 */
-		verifyApiKey: (params: { body: { key: string } }) => Promise<{
-			valid: boolean;
-			error?: { message: string; code: string } | null;
-			key?: {
-				id: string;
-				name?: string;
-				userId?: string;
-				permissions?: Record<string, string[]> | null;
-			} | null;
-		}>;
-	} & DefaultPluginApiMethods;
-}
-
-/**
- * Safely parse a URL and return its origin, or undefined if invalid.
- */
-function safeOrigin(url: string | undefined): string | undefined {
-	if (!url) return undefined;
-	try {
-		return new URL(url).origin;
-	} catch {
-		return undefined;
-	}
-}
-
-/**
- * Parse a domain or URL into an origin.
- * Handles both full URLs (https://example.com) and bare domains (example.com).
- * Bare domains default to https:// scheme.
- */
-function parseOriginLike(value: string): string | undefined {
-	const trimmed = value.trim();
-	if (!trimmed) return undefined;
-
-	// If it looks like a URL with scheme, parse as-is
-	if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(trimmed)) {
-		return safeOrigin(trimmed);
-	}
-
-	// Otherwise, treat as host[:port] and assume https
-	return safeOrigin(`https://${trimmed}`);
-}
-
-/**
- * Resolve the base URL for the auth instance.
- *
- * Priority:
- * 1. Explicit `baseURL` option
- * 2. `AGENTUITY_BASE_URL` env var (Agentuity platform-injected)
- * 3. `BETTER_AUTH_URL` env var (BetterAuth standard, for 3rd party SDK compatibility)
- */
-function resolveBaseURL(explicitBaseURL?: string): string | undefined {
-	return explicitBaseURL ?? process.env.AGENTUITY_BASE_URL ?? process.env.BETTER_AUTH_URL;
-}
-
-/**
- * Resolve the auth secret.
- *
- * Priority:
- * 1. Explicit `secret` option
- * 2. `AGENTUITY_AUTH_SECRET` env var (Agentuity convention)
- * 3. `BETTER_AUTH_SECRET` env var (BetterAuth standard, for backward compatibility)
- */
-function resolveSecret(explicitSecret?: string): string | undefined {
-	return explicitSecret ?? process.env.AGENTUITY_AUTH_SECRET ?? process.env.BETTER_AUTH_SECRET;
-}
-
-/**
- * Create the default trustedOrigins function for Agentuity deployments.
- *
- * This provides zero-config CORS/origin handling:
- * - Trusts the resolved baseURL origin
- * - Trusts the AGENTUITY_BASE_URL origin
- * - Trusts all domains from AGENTUITY_CLOUD_DOMAINS (platform-set, comma-separated)
- * - Trusts additional domains from AUTH_TRUSTED_DOMAINS (developer-set, comma-separated)
- * - Trusts the same-origin of incoming requests (request.url.origin)
- *
- * @param baseURL - The resolved base URL for the auth instance
- */
-function createDefaultTrustedOrigins(baseURL?: string): (request?: Request) => Promise<string[]> {
-	const agentuityURL = process.env.AGENTUITY_BASE_URL;
-	const cloudDomains = process.env.AGENTUITY_CLOUD_DOMAINS;
-	const devTrustedDomains = process.env.AUTH_TRUSTED_DOMAINS;
-
-	const staticOrigins = new Set<string>();
-
-	const baseOrigin = safeOrigin(baseURL);
-	if (baseOrigin) staticOrigins.add(baseOrigin);
-
-	const agentuityOrigin = safeOrigin(agentuityURL);
-	if (agentuityOrigin) staticOrigins.add(agentuityOrigin);
-
-	// Platform-set cloud domains (deployment, project, PR, custom domains, tunnels)
-	if (cloudDomains) {
-		for (const raw of cloudDomains.split(',')) {
-			const origin = parseOriginLike(raw);
-			if (origin) staticOrigins.add(origin);
-		}
-	}
-
-	// Developer-set additional trusted domains
-	if (devTrustedDomains) {
-		for (const raw of devTrustedDomains.split(',')) {
-			const origin = parseOriginLike(raw);
-			if (origin) staticOrigins.add(origin);
-		}
-	}
-
-	return async (request?: Request): Promise<string[]> => {
-		const origins = new Set(staticOrigins);
-
-		if (request) {
-			const requestOrigin = safeOrigin(request.url);
-			if (requestOrigin) origins.add(requestOrigin);
-		}
-
-		return [...origins];
-	};
-}
-
-/**
- * Configuration options for auth.
- * Extends BetterAuth options with Agentuity-specific settings.
- */
-export interface AuthOptions extends BetterAuthOptions {
-	/**
-	 * PostgreSQL connection string.
-	 * When provided, we create a Bun SQL connection and Drizzle instance internally.
-	 * This is the simplest path - just provide the connection string.
-	 *
-	 * @example
-	 * ```typescript
-	 * createAuth({
-	 *   connectionString: process.env.DATABASE_URL,
-	 * });
-	 * ```
-	 */
-	connectionString?: string;
-
-	/**
-	 * Skip default plugins (organization, jwt, bearer, apiKey).
-	 * Use this if you want full control over plugins.
-	 */
-	skipDefaultPlugins?: boolean;
-
-	/**
-	 * API Key plugin configuration.
-	 * Set to false to disable the API key plugin entirely.
-	 */
-	apiKey?: ApiKeyPluginOptions | false;
-}
-
-/**
- * Default plugins included with Agentuity auth.
- *
- * @param apiKeyOptions - API key plugin options, or false to disable
- */
-export function getDefaultPlugins(apiKeyOptions?: ApiKeyPluginOptions | false) {
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	const plugins: any[] = [organization(), jwt(), bearer()];
-
-	// Add API key plugin unless explicitly disabled
-	if (apiKeyOptions !== false) {
-		const opts = { ...DEFAULT_API_KEY_OPTIONS, ...apiKeyOptions };
-
-		if (opts.enabled) {
-			plugins.push(
-				apiKey({
-					apiKeyHeaders: opts.apiKeyHeaders,
-					enableSessionForAPIKeys: opts.enableSessionForAPIKeys,
-					defaultPrefix: opts.defaultPrefix,
-					defaultKeyLength: opts.defaultKeyLength,
-					enableMetadata: opts.enableMetadata,
-				})
-			);
-		}
-	}
-
-	return plugins;
-}
-
-/**
- * Create an Auth instance.
- *
- * This wraps BetterAuth with sensible defaults for Agentuity projects:
- * - Default basePath: '/api/auth'
- * - Email/password authentication enabled by default
- * - Organization plugin for multi-tenancy
- * - JWT plugin for token-based auth
- * - Bearer plugin for API auth
- * - API Key plugin for programmatic access
- * - Experimental joins enabled by default for better performance
- *
- * @example Option A: Connection string (simplest)
- * ```typescript
- * import { createAuth } from '@agentuity/auth';
- *
- * export const auth = createAuth({
- *   connectionString: process.env.DATABASE_URL,
- * });
- * ```
- *
- * @example Option B: Bring your own Drizzle
- * ```typescript
- * import { drizzle } from 'drizzle-orm/bun-sql';
- * import { drizzleAdapter } from 'better-auth/adapters/drizzle';
- * import * as authSchema from '@agentuity/auth/schema';
- *
- * const schema = { ...authSchema, ...myAppSchema };
- * const db = drizzle(connectionString, { schema });
- *
- * export const auth = createAuth({
- *   database: drizzleAdapter(db, { provider: 'pg', schema: authSchema }),
- * });
- * ```
- *
- * @example Option C: Other adapters (Prisma, MongoDB, etc.)
- * ```typescript
- * import { prismaAdapter } from 'better-auth/adapters/prisma';
- *
- * export const auth = createAuth({
- *   database: prismaAdapter(new PrismaClient()),
- * });
- * ```
- */
-export function createAuth<T extends AuthOptions>(options: T) {
-	const {
-		skipDefaultPlugins,
-		plugins = [],
-		apiKey: apiKeyOptions,
-		connectionString,
-		...restOptions
-	} = options;
-
-	const resolvedBaseURL = resolveBaseURL(restOptions.baseURL);
-	const resolvedSecret = resolveSecret(restOptions.secret);
-
-	// Apply Agentuity defaults
-	const basePath = restOptions.basePath ?? '/api/auth';
-	const emailAndPassword = restOptions.emailAndPassword ?? { enabled: true };
-
-	// Explicitly type to avoid union type inference issues with downstream consumers
-	const trustedOrigins: TrustedOrigins =
-		restOptions.trustedOrigins ?? createDefaultTrustedOrigins(resolvedBaseURL);
-
-	const defaultPlugins = skipDefaultPlugins ? [] : getDefaultPlugins(apiKeyOptions);
-
-	// Handle database configuration
-	let database = restOptions.database;
-
-	// ConnectionString provided - create Bun SQL connection + drizzle internally
-	if (connectionString && !database) {
-		const db = drizzle(connectionString, { schema: authSchema });
-		database = drizzleAdapter(db, {
-			provider: 'pg',
-			schema: authSchema,
-		});
-	}
-
-	// Default experimental.joins to true for better performance
-	const experimental = {
-		joins: true,
-		...restOptions.experimental,
-	};
-
-	const authInstance = betterAuth({
-		...restOptions,
-		database,
-		basePath,
-		emailAndPassword,
-		experimental,
-		...(resolvedBaseURL ? { baseURL: resolvedBaseURL } : {}),
-		...(resolvedSecret ? { secret: resolvedSecret } : {}),
-		trustedOrigins,
-		plugins: [...defaultPlugins, ...plugins],
-	});
-
-	return authInstance as AuthBase &
-		typeof authInstance & {
-			api: typeof authInstance.api & DefaultPluginApiMethods;
-		};
-}
-
-/**
- * Type helper for the auth instance with default plugin methods.
- * Inferred from createAuth to stay in sync with BetterAuth.
- */
-export type AuthInstance = ReturnType<typeof createAuth>;

package/src/agentuity/plugins/api-key.ts

@@ -1,158 +0,0 @@
-/**
- * API Key plugin types for @agentuity/auth.
- *
- * Server-side API methods for API key management provided by BetterAuth's
- * API Key plugin. Enables programmatic access to your application.
- *
- * @see https://better-auth.com/docs/plugins/api-key
- * @module agentuity/plugins/api-key
- */
-
-/**
- * API Key data returned from API calls.
- */
-export interface ApiKey {
-	id: string;
-	name: string;
-	key?: string;
-	start?: string;
-	userId?: string;
-	expiresAt?: Date | null;
-	createdAt: Date;
-	permissions?: Record<string, string[]> | null;
-	metadata?: Record<string, unknown> | null;
-}
-
-/**
- * API Key plugin configuration options.
- */
-export interface ApiKeyPluginOptions {
-	/**
-	 * Whether to enable API key authentication.
-	 * Defaults to true.
-	 */
-	enabled?: boolean;
-
-	/**
-	 * Header names to check for API key.
-	 * Defaults to ['x-agentuity-auth-api-key', 'X-Agentuity-Auth-Api-Key'].
-	 */
-	apiKeyHeaders?: string[];
-
-	/**
-	 * Whether API keys should create mock sessions for the user.
-	 * This allows API key auth to work seamlessly with session-based middleware.
-	 * Defaults to true.
-	 */
-	enableSessionForAPIKeys?: boolean;
-
-	/**
-	 * Default prefix for generated API keys.
-	 * Defaults to 'ag_'.
-	 */
-	defaultPrefix?: string;
-
-	/**
-	 * Default length for generated API keys (excluding prefix).
-	 * Defaults to 64.
-	 */
-	defaultKeyLength?: number;
-
-	/**
-	 * Whether to enable metadata storage on API keys.
-	 * Defaults to true.
-	 */
-	enableMetadata?: boolean;
-}
-
-/**
- * Default API key plugin options.
- */
-export const DEFAULT_API_KEY_OPTIONS: Required<ApiKeyPluginOptions> = {
-	enabled: true,
-	apiKeyHeaders: ['x-agentuity-auth-api-key', 'X-Agentuity-Auth-Api-Key'],
-	enableSessionForAPIKeys: true,
-	defaultPrefix: 'ag_',
-	defaultKeyLength: 64,
-	enableMetadata: true,
-};
-
-/**
- * Server-side API methods for API key management.
- *
- * These methods are added by the BetterAuth API Key plugin and provide
- * programmatic access to your application via API keys.
- *
- * @see https://better-auth.com/docs/plugins/api-key
- */
-export interface ApiKeyApiMethods {
-	/**
-	 * Create a new API key.
-	 *
-	 * When using session headers, the key is created for the authenticated user.
-	 * For server-side creation (without headers), pass `userId` explicitly.
-	 *
-	 * **Important:** The full API key is only returned once at creation time.
-	 * Store it securely - it cannot be retrieved later.
-	 */
-	createApiKey: (params: {
-		body: {
-			name?: string;
-			expiresIn?: number;
-			prefix?: string;
-			userId?: string;
-			permissions?: Record<string, string[]>;
-			remaining?: number;
-			metadata?: Record<string, unknown>;
-			refillAmount?: number;
-			refillInterval?: number;
-			rateLimitTimeWindow?: number;
-			rateLimitMax?: number;
-			rateLimitEnabled?: boolean;
-		};
-		headers?: Headers;
-	}) => Promise<ApiKey>;
-
-	/**
-	 * List all API keys for the authenticated user.
-	 *
-	 * Note: The full key value is not returned - only the `start` prefix
-	 * for identification purposes.
-	 */
-	listApiKeys: (params: { headers?: Headers }) => Promise<
-		Array<{
-			id: string;
-			name: string;
-			start: string;
-			expiresAt?: Date | null;
-			createdAt: Date;
-		}>
-	>;
-
-	/**
-	 * Delete an API key.
-	 *
-	 * The key is immediately revoked and can no longer be used for authentication.
-	 */
-	deleteApiKey: (params: {
-		body: { keyId: string };
-		headers?: Headers;
-	}) => Promise<{ success: boolean }>;
-
-	/**
-	 * Verify an API key and get its metadata.
-	 *
-	 * Used internally by middleware, but can also be called directly
-	 * for custom API key validation logic.
-	 */
-	verifyApiKey: (params: { body: { key: string }; headers?: Headers }) => Promise<{
-		valid: boolean;
-		error?: { message: string; code: string } | null;
-		key?: {
-			id: string;
-			name: string;
-			userId: string;
-			permissions?: Record<string, string[]> | null;
-		} | null;
-	}>;
-}

package/src/agentuity/plugins/index.ts

@@ -1,35 +0,0 @@
-/**
- * Plugin type exports for @agentuity/auth.
- *
- * This module re-exports all plugin-specific types and interfaces for
- * convenient access. Each plugin has its own file for easier maintenance.
- *
- * @module agentuity/plugins
- */
-
-// Organization plugin
-export type {
-	Organization,
-	OrganizationMember,
-	OrganizationInvitation,
-	OrganizationApiMethods,
-} from './organization';
-
-// API Key plugin
-export type { ApiKey, ApiKeyPluginOptions, ApiKeyApiMethods } from './api-key';
-export { DEFAULT_API_KEY_OPTIONS } from './api-key';
-
-// JWT plugin
-export type { JwtApiMethods } from './jwt';
-
-/**
- * Combined API extensions from all default plugins.
- *
- * This type represents all the server-side API methods added by the
- * default Agentuity auth plugins (organization, jwt, bearer, apiKey).
- */
-import type { OrganizationApiMethods } from './organization';
-import type { ApiKeyApiMethods } from './api-key';
-import type { JwtApiMethods } from './jwt';
-
-export type DefaultPluginApiMethods = OrganizationApiMethods & ApiKeyApiMethods & JwtApiMethods;

package/src/agentuity/plugins/jwt.ts

@@ -1,30 +0,0 @@
-/**
- * JWT plugin types for @agentuity/auth.
- *
- * Server-side API methods for JWT token management provided by BetterAuth's
- * JWT plugin. Enables token-based authentication.
- *
- * @see https://better-auth.com/docs/plugins/jwt
- * @module agentuity/plugins/jwt
- */
-
-/**
- * Server-side API methods for JWT token management.
- *
- * These methods are added by the BetterAuth JWT plugin and provide
- * JWT token generation for authenticated users.
- *
- * @see https://better-auth.com/docs/plugins/jwt
- */
-export interface JwtApiMethods {
-	/**
-	 * Get a JWT token for the authenticated user.
-	 *
-	 * The token can be used with the Bearer plugin for stateless
-	 * authentication in subsequent requests.
-	 *
-	 * The JWKS endpoint for token verification is available at:
-	 * `{baseURL}/api/auth/.well-known/jwks.json`
-	 */
-	getToken: (params: { headers?: Headers }) => Promise<{ token: string }>;
-}