clearauth 0.3.0

package/dist/createMechAuth.js

@@ -0,0 +1,215 @@
+/**
+ * Factory function to create a complete ClearAuth configuration
+ *
+ * This module provides a convenient way to create a fully configured ClearAuthConfig
+ * with sensible defaults for session management, cookies, and security settings.
+ *
+ * @module createClearAuth
+ */
+import { createMechKysely } from "./mech-kysely.js";
+import { ClearAuthConfigError } from "./errors.js";
+import { getDefaultLogger } from "./logger.js";
+import { createPbkdf2PasswordHasher } from "./password-hasher.js";
+// ============================================================================
+// Session & Cookie Presets
+// ============================================================================
+/**
+ * Default session configuration
+ * - 7 day expiration
+ * - Secure cookies in production
+ * - SameSite: lax
+ */
+export const defaultSessionConfig = {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    cookie: {
+        name: 'session',
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+    },
+};
+/**
+ * Short-lived session configuration (for high-security apps)
+ * - 1 hour expiration
+ * - Strict cookies
+ */
+export const shortSessionConfig = {
+    expiresIn: 60 * 60, // 1 hour
+    cookie: {
+        name: 'session',
+        httpOnly: true,
+        sameSite: 'strict',
+        path: '/',
+    },
+};
+/**
+ * Long-lived session configuration (for consumer apps)
+ * - 30 day expiration
+ * - Lax cookies for better UX
+ */
+export const longSessionConfig = {
+    expiresIn: 60 * 60 * 24 * 30, // 30 days
+    cookie: {
+        name: 'session',
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+    },
+};
+/**
+ * Helper to check if database config is the simplified format
+ */
+function isSimpleDatabaseConfig(db) {
+    return db !== null && typeof db === 'object' && 'appId' in db && 'apiKey' in db;
+}
+/**
+ * Create a complete ClearAuth configuration
+ *
+ * All configuration must be provided explicitly - no environment variables are read.
+ *
+ * Configuration formats:
+ *
+ * 1. **Simplified config (recommended)**:
+ *    ```ts
+ *    const config = createClearAuth({
+ *      secret: "your-secret-key",
+ *      baseUrl: "https://yourdomain.com",
+ *      database: { appId: "...", apiKey: "..." },
+ *      isProduction: true,
+ *      oauth: {
+ *        github: {
+ *          clientId: env.GITHUB_CLIENT_ID,
+ *          clientSecret: env.GITHUB_CLIENT_SECRET,
+ *          redirectUri: 'https://yourdomain.com/auth/callback/github',
+ *        },
+ *      },
+ *    })
+ *    ```
+ *
+ * 2. **With session presets**:
+ *    ```ts
+ *    const config = createClearAuth({
+ *      secret: "your-secret-key",
+ *      baseUrl: "https://yourdomain.com",
+ *      database: { appId: "...", apiKey: "..." },
+ *      session: longSessionConfig, // Use 30-day sessions
+ *    })
+ *    ```
+ *
+ * @param options - Configuration options
+ * @returns A configured ClearAuthConfig object
+ * @throws ClearAuthConfigError if required config is missing or invalid
+ *
+ * @example Cloudflare Workers setup
+ * ```ts
+ * import { createClearAuth, defaultSessionConfig } from 'clearauth'
+ *
+ * const config = createClearAuth({
+ *   secret: env.AUTH_SECRET,
+ *   baseUrl: 'https://yourdomain.com',
+ *   database: {
+ *     appId: env.MECH_APP_ID,
+ *     apiKey: env.MECH_API_KEY,
+ *   },
+ *   isProduction: true,
+ *   session: defaultSessionConfig,
+ *   oauth: {
+ *     github: {
+ *       clientId: env.GITHUB_CLIENT_ID,
+ *       clientSecret: env.GITHUB_CLIENT_SECRET,
+ *       redirectUri: 'https://yourdomain.com/auth/callback/github',
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * @example Next.js setup
+ * ```ts
+ * import { createClearAuth } from 'clearauth'
+ *
+ * export const authConfig = createClearAuth({
+ *   secret: process.env.AUTH_SECRET!,
+ *   baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
+ *   database: {
+ *     appId: process.env.MECH_APP_ID!,
+ *     apiKey: process.env.MECH_API_KEY!,
+ *   },
+ *   oauth: {
+ *     github: {
+ *       clientId: process.env.GITHUB_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *       redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/auth/callback/github`,
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export function createClearAuth(options) {
+    const logger = getDefaultLogger();
+    // Validate required fields
+    if (!options.secret) {
+        throw new ClearAuthConfigError("secret is required", { isProduction: options.isProduction });
+    }
+    if (!options.baseUrl) {
+        throw new ClearAuthConfigError("baseUrl is required", { isProduction: options.isProduction });
+    }
+    // Warn about development defaults
+    if (options.secret === "better-auth-secret-123456789" || options.secret === "dev-secret-key") {
+        if (options.isProduction) {
+            throw new ClearAuthConfigError("Cannot use default secret in production", { isProduction: options.isProduction });
+        }
+        logger.warn("Using default secret. This is only safe in development.");
+    }
+    // Determine database config format
+    let kyselyConfig;
+    if (isSimpleDatabaseConfig(options.database)) {
+        // Simplified format: { appId, apiKey, ... }
+        logger.debug("Creating auth config with simplified database config");
+        kyselyConfig = {
+            appId: options.database.appId,
+            apiKey: options.database.apiKey,
+            baseUrl: options.database.baseUrl,
+            appSchemaId: options.database.appSchemaId,
+            timeout: options.database.timeout,
+            maxRetries: options.database.maxRetries,
+        };
+    }
+    else if ('config' in options.database) {
+        // Full config format: { config: MechKyselyConfig }
+        logger.debug("Creating auth config with full database config");
+        kyselyConfig = options.database.config;
+    }
+    else {
+        throw new ClearAuthConfigError("Invalid database configuration format", {
+            database: options.database
+        });
+    }
+    try {
+        logger.debug("Creating Kysely instance...");
+        const db = createMechKysely(kyselyConfig);
+        logger.debug("Kysely created successfully");
+        // Build final config
+        const config = {
+            database: db,
+            secret: options.secret,
+            baseUrl: options.baseUrl,
+            isProduction: options.isProduction ?? false,
+            session: options.session ?? defaultSessionConfig,
+            oauth: options.oauth,
+            password: options.password ?? {
+                minLength: 8,
+            },
+            passwordHasher: options.passwordHasher ?? createPbkdf2PasswordHasher(),
+        };
+        return config;
+    }
+    catch (err) {
+        if (err instanceof ClearAuthConfigError) {
+            throw err;
+        }
+        throw new ClearAuthConfigError(`Failed to create ClearAuth config: ${err.message}`, {
+            originalError: err.message
+        });
+    }
+}
+//# sourceMappingURL=createMechAuth.js.map

package/dist/createMechAuth.js.map

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

package/dist/database/schema.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Database Schema Types
+ *
+ * TypeScript interfaces and Kysely types for the mech-auth database schema.
+ * These types must match the SQL schema defined in the migration files.
+ *
+ * @see /migrations/001_create_users_table.sql
+ * @see /migrations/002_create_sessions_table.sql
+ * @see /migrations/003_create_verification_tokens.sql
+ * @see /migrations/004_create_reset_tokens.sql
+ */
+import type { ColumnType, Selectable, Insertable, Updateable } from 'kysely';
+/**
+ * Users Table
+ *
+ * Core users table with support for email/password and OAuth authentication.
+ */
+export interface UsersTable {
+    id: ColumnType<string, string | undefined, never>;
+    email: string;
+    email_verified: ColumnType<boolean, boolean | undefined, boolean>;
+    password_hash: string | null;
+    github_id: string | null;
+    google_id: string | null;
+    name: string | null;
+    avatar_url: string | null;
+    created_at: ColumnType<Date, Date | undefined, never>;
+    updated_at: ColumnType<Date, Date | undefined, Date>;
+}
+/**
+ * Sessions Table
+ *
+ * Session management with expiration tracking.
+ * Session IDs are generated by the application using Oslo.
+ */
+export interface SessionsTable {
+    id: string;
+    user_id: string;
+    expires_at: Date;
+    ip_address: string | null;
+    user_agent: string | null;
+    created_at: ColumnType<Date, Date | undefined, never>;
+}
+/**
+ * Email Verification Tokens Table
+ *
+ * Tokens for email verification flow.
+ * Typically expire after 24 hours.
+ */
+export interface EmailVerificationTokensTable {
+    token: string;
+    user_id: string;
+    email: string;
+    expires_at: Date;
+    created_at: ColumnType<Date, Date | undefined, never>;
+}
+/**
+ * Password Reset Tokens Table
+ *
+ * Tokens for password reset flow.
+ * Typically expire after 1 hour for security.
+ */
+export interface PasswordResetTokensTable {
+    token: string;
+    user_id: string;
+    expires_at: Date;
+    created_at: ColumnType<Date, Date | undefined, never>;
+}
+/**
+ * Database Schema
+ *
+ * Complete database schema for Kysely type-safe queries.
+ */
+export interface Database {
+    users: UsersTable;
+    sessions: SessionsTable;
+    email_verification_tokens: EmailVerificationTokensTable;
+    password_reset_tokens: PasswordResetTokensTable;
+}
+/**
+ * Type-safe row types for SELECT queries
+ */
+export type User = Selectable<UsersTable>;
+export type Session = Selectable<SessionsTable>;
+export type EmailVerificationToken = Selectable<EmailVerificationTokensTable>;
+export type PasswordResetToken = Selectable<PasswordResetTokensTable>;
+/**
+ * Type-safe input types for INSERT queries
+ */
+export type NewUser = Insertable<UsersTable>;
+export type NewSession = Insertable<SessionsTable>;
+export type NewEmailVerificationToken = Insertable<EmailVerificationTokensTable>;
+export type NewPasswordResetToken = Insertable<PasswordResetTokensTable>;
+/**
+ * Type-safe input types for UPDATE queries
+ */
+export type UserUpdate = Updateable<UsersTable>;
+export type SessionUpdate = Updateable<SessionsTable>;
+export type EmailVerificationTokenUpdate = Updateable<EmailVerificationTokensTable>;
+export type PasswordResetTokenUpdate = Updateable<PasswordResetTokensTable>;
+/**
+ * User with session information (common join result)
+ */
+export interface UserWithSession {
+    user: User;
+    session: Session;
+}
+/**
+ * Public user profile (safe to expose to client)
+ */
+export interface PublicUser {
+    id: string;
+    email: string;
+    email_verified: boolean;
+    name: string | null;
+    avatar_url: string | null;
+    created_at: Date;
+}
+/**
+ * Session with user information (common join result)
+ */
+export interface SessionWithUser {
+    session: Session;
+    user: PublicUser;
+}
+/**
+ * Helper function to convert User to PublicUser
+ */
+export declare function toPublicUser(user: User): PublicUser;
+/**
+ * Type guards
+ */
+export declare function isValidSession(session: Session): boolean;
+export declare function isValidEmailVerificationToken(token: EmailVerificationToken): boolean;
+export declare function isValidPasswordResetToken(token: PasswordResetToken): boolean;

package/dist/database/schema.js

@@ -0,0 +1,37 @@
+/**
+ * Database Schema Types
+ *
+ * TypeScript interfaces and Kysely types for the mech-auth database schema.
+ * These types must match the SQL schema defined in the migration files.
+ *
+ * @see /migrations/001_create_users_table.sql
+ * @see /migrations/002_create_sessions_table.sql
+ * @see /migrations/003_create_verification_tokens.sql
+ * @see /migrations/004_create_reset_tokens.sql
+ */
+/**
+ * Helper function to convert User to PublicUser
+ */
+export function toPublicUser(user) {
+    return {
+        id: user.id,
+        email: user.email,
+        email_verified: user.email_verified,
+        name: user.name,
+        avatar_url: user.avatar_url,
+        created_at: user.created_at,
+    };
+}
+/**
+ * Type guards
+ */
+export function isValidSession(session) {
+    return new Date(session.expires_at) > new Date();
+}
+export function isValidEmailVerificationToken(token) {
+    return new Date(token.expires_at) > new Date();
+}
+export function isValidPasswordResetToken(token) {
+    return new Date(token.expires_at) > new Date();
+}
+//# sourceMappingURL=schema.js.map

package/dist/database/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/database/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsIH;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,IAAI,EAAE,CAAA;AAClD,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,KAA6B;IACzE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,IAAI,EAAE,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAyB;IACjE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,IAAI,EAAE,CAAA;AAChD,CAAC"}

package/dist/edge.d.ts

@@ -0,0 +1,4 @@
+import type { ClearAuthConfig } from "./types.js";
+export { createClearAuth, defaultSessionConfig, longSessionConfig, shortSessionConfig, } from "./createMechAuth.js";
+export type { CorsConfig, ClearAuthConfig, OAuthProviderConfig, OAuthProvidersConfig, SessionConfig } from "./types.js";
+export declare function handleClearAuthEdgeRequest(request: Request, config: ClearAuthConfig): Promise<Response>;

package/dist/edge.js

@@ -0,0 +1,6 @@
+import { handleClearAuthRequest } from "./handler.js";
+export { createClearAuth, defaultSessionConfig, longSessionConfig, shortSessionConfig, } from "./createMechAuth.js";
+export async function handleClearAuthEdgeRequest(request, config) {
+    return await handleClearAuthRequest(request, config);
+}
+//# sourceMappingURL=edge.js.map

package/dist/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAErD,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAG5B,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,OAAgB,EAAE,MAAuB;IACxF,OAAO,MAAM,sBAAsB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AACtD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Error types for ClearAuth
+ */
+export declare class ClearAuthError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+export declare class ClearAuthSqlError extends ClearAuthError {
+    constructor(message: string, details?: Record<string, any>);
+}
+export declare class ClearAuthConfigError extends ClearAuthError {
+    constructor(message: string, details?: Record<string, any>);
+}
+export declare class ClearAuthNetworkError extends ClearAuthError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: Record<string, any>);
+}
+export declare class ClearAuthTimeoutError extends ClearAuthError {
+    constructor(message: string, details?: Record<string, any>);
+}
+export declare class ClearAuthRateLimitError extends ClearAuthError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number, details?: Record<string, any>);
+}

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Error types for ClearAuth
+ */
+export class ClearAuthError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ClearAuthError";
+    }
+}
+export class ClearAuthSqlError extends ClearAuthError {
+    constructor(message, details) {
+        super(message, "CLEARAUTH_SQL_ERROR", details);
+        this.name = "ClearAuthSqlError";
+    }
+}
+export class ClearAuthConfigError extends ClearAuthError {
+    constructor(message, details) {
+        super(message, "CLEARAUTH_CONFIG_ERROR", details);
+        this.name = "ClearAuthConfigError";
+    }
+}
+export class ClearAuthNetworkError extends ClearAuthError {
+    constructor(message, statusCode, details) {
+        super(message, "CLEARAUTH_NETWORK_ERROR", details);
+        this.statusCode = statusCode;
+        this.name = "ClearAuthNetworkError";
+    }
+}
+export class ClearAuthTimeoutError extends ClearAuthError {
+    constructor(message, details) {
+        super(message, "CLEARAUTH_TIMEOUT_ERROR", details);
+        this.name = "ClearAuthTimeoutError";
+    }
+}
+export class ClearAuthRateLimitError extends ClearAuthError {
+    constructor(retryAfter, details) {
+        super(`Rate limit exceeded. Retry after ${retryAfter}ms`, "CLEARAUTH_RATE_LIMIT_ERROR", details);
+        this.retryAfter = retryAfter;
+        this.name = "ClearAuthRateLimitError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe,EAAkB,IAAY,EAAkB,OAA6B;QACtG,KAAK,CAAC,OAAO,CAAC,CAAA;QAD6B,SAAI,GAAJ,IAAI,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAsB;QAEtG,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,qBAAqB,EAAE,OAAO,CAAC,CAAA;QAC9C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;IACjC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,wBAAwB,EAAE,OAAO,CAAC,CAAA;QACjD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,OAAe,EAAkB,UAAmB,EAAE,OAA6B;QAC7F,KAAK,CAAC,OAAO,EAAE,yBAAyB,EAAE,OAAO,CAAC,CAAA;QADP,eAAU,GAAV,UAAU,CAAS;QAE9D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,yBAAyB,EAAE,OAAO,CAAC,CAAA;QAClD,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IACzD,YAA4B,UAAkB,EAAE,OAA6B;QAC3E,KAAK,CAAC,oCAAoC,UAAU,IAAI,EAAE,4BAA4B,EAAE,OAAO,CAAC,CAAA;QADtE,eAAU,GAAV,UAAU,CAAQ;QAE5C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF"}

package/dist/handler.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Unified HTTP request handler for ClearAuth
+ *
+ * This module provides a single entry point for handling all authentication requests,
+ * automatically routing to the appropriate handler (OAuth or email/password).
+ *
+ * @module handler
+ */
+import type { ClearAuthConfig } from './types.js';
+/**
+ * Unified authentication request handler
+ *
+ * Automatically routes requests to the appropriate handler based on the URL path:
+ * - OAuth routes: `/auth/oauth/*`, `/auth/github/*`, `/auth/google/*`, `/auth/callback/*`
+ * - Email/password routes: All other `/auth/*` routes
+ *
+ * @param request - The HTTP request to handle
+ * @param config - ClearAuth configuration
+ * @returns HTTP response
+ *
+ * @example
+ * ```typescript
+ * // Cloudflare Workers
+ * export default {
+ *   async fetch(request: Request, env: Env): Promise<Response> {
+ *     const config: ClearAuthConfig = {
+ *       database: createMechKysely({ appId: env.MECH_APP_ID, apiKey: env.MECH_API_KEY }),
+ *       secret: env.AUTH_SECRET,
+ *       baseUrl: 'https://yourdomain.com',
+ *       oauth: {
+ *         github: {
+ *           clientId: env.GITHUB_CLIENT_ID,
+ *           clientSecret: env.GITHUB_CLIENT_SECRET,
+ *           redirectUri: 'https://yourdomain.com/auth/callback/github',
+ *         },
+ *       },
+ *     }
+ *     return handleClearAuthRequest(request, config)
+ *   },
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Next.js API route
+ * import { handleClearAuthRequest } from 'clearauth'
+ * import { config } from '@/lib/auth-config'
+ *
+ * export async function GET(request: Request) {
+ *   return handleClearAuthRequest(request, config)
+ * }
+ *
+ * export async function POST(request: Request) {
+ *   return handleClearAuthRequest(request, config)
+ * }
+ * ```
+ */
+export declare function handleClearAuthRequest(request: Request, config: ClearAuthConfig): Promise<Response>;
+/**
+ * Get a list of all supported routes
+ *
+ * Useful for debugging and documentation purposes.
+ *
+ * @returns Object containing OAuth and auth routes
+ *
+ * @example
+ * ```typescript
+ * const routes = getSupportedRoutes()
+ * console.log('OAuth routes:', routes.oauth)
+ * console.log('Auth routes:', routes.auth)
+ * ```
+ */
+export declare function getSupportedRoutes(): {
+    oauth: {
+        method: string;
+        path: string;
+        description: string;
+    }[];
+    auth: {
+        method: string;
+        path: string;
+        description: string;
+    }[];
+};
+/**
+ * Health check endpoint
+ *
+ * Returns a simple health check response to verify the auth service is running.
+ *
+ * @returns HTTP response with health status
+ *
+ * @example
+ * ```typescript
+ * // In your handler
+ * if (url.pathname === '/auth/health') {
+ *   return healthCheck()
+ * }
+ * ```
+ */
+export declare function healthCheck(): Response;