clearauth 0.3.0

package/dist/auth/utils.js

@@ -0,0 +1,121 @@
+/**
+ * Authentication Utilities
+ *
+ * Shared utilities for email/password authentication including:
+ * - Email validation
+ * - Password validation
+ * - Secure token generation
+ */
+import { base64url } from 'oslo/encoding';
+/**
+ * Email validation regex (RFC 5322 simplified)
+ *
+ * Must have:
+ * - Local part before @
+ * - @ symbol
+ * - Domain name
+ * - At least one dot (.)
+ * - TLD with at least 1 character after the dot
+ *
+ * Does NOT allow:
+ * - Consecutive dots (..)
+ * - Leading/trailing dots
+ * - @ at start
+ * - Spaces
+ */
+const EMAIL_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/;
+/**
+ * Validate email format
+ *
+ * @param email - Email address to validate
+ * @returns True if valid, false otherwise
+ */
+export function isValidEmail(email) {
+    if (!email || email.length > 254) {
+        return false;
+    }
+    // Check for spaces (not allowed in email addresses)
+    if (email.includes(' ')) {
+        return false;
+    }
+    const trimmedEmail = email.toLowerCase().trim();
+    // Check for consecutive dots
+    if (trimmedEmail.includes('..')) {
+        return false;
+    }
+    // Check for leading/trailing dots
+    const localPart = trimmedEmail.split('@')[0];
+    if (localPart?.startsWith('.') || localPart?.endsWith('.')) {
+        return false;
+    }
+    return EMAIL_REGEX.test(trimmedEmail);
+}
+/**
+ * Validate password strength
+ *
+ * @param password - Password to validate
+ * @param minLength - Minimum password length (default: 8)
+ * @returns Error message if invalid, null if valid
+ */
+export function validatePassword(password, minLength = 8) {
+    if (!password || password.length === 0) {
+        return `Password must be at least ${minLength} characters long`;
+    }
+    if (password.length < minLength) {
+        return `Password must be at least ${minLength} characters long`;
+    }
+    // Optional: Add more password strength requirements
+    // - At least one uppercase letter
+    // - At least one lowercase letter
+    // - At least one number
+    // - At least one special character
+    return null;
+}
+/**
+ * Generate a secure random token
+ *
+ * Uses cryptographically secure random values from Web Crypto API.
+ *
+ * @param entropySize - Number of bytes of entropy (default: 32)
+ * @returns Base64url-encoded token
+ *
+ * @example
+ * ```ts
+ * const token = generateSecureToken(32) // 256 bits of entropy
+ * ```
+ */
+export function generateSecureToken(entropySize = 32) {
+    const bytes = new Uint8Array(entropySize);
+    crypto.getRandomValues(bytes);
+    // Use base64url encoder without padding
+    return base64url.encode(bytes).replace(/=/g, '');
+}
+/**
+ * Normalize email address
+ *
+ * Converts email to lowercase for consistent storage and comparison.
+ *
+ * @param email - Email address to normalize
+ * @returns Normalized email address
+ */
+export function normalizeEmail(email) {
+    return email.toLowerCase().trim();
+}
+/**
+ * Authentication error types
+ */
+export class AuthError extends Error {
+    constructor(message, code, statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = 'AuthError';
+    }
+}
+/**
+ * Create a standardized auth error
+ */
+export function createAuthError(message, code, statusCode = 400) {
+    return new AuthError(message, code, statusCode);
+}
+//# sourceMappingURL=utils.js.map

package/dist/auth/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/auth/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,GAAG,sIAAsI,CAAA;AAE1J;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACjC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,oDAAoD;IACpD,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,YAAY,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IAE/C,6BAA6B;IAC7B,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,kCAAkC;IAClC,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,IAAI,SAAS,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,YAAoB,CAAC;IACtE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,6BAA6B,SAAS,kBAAkB,CAAA;IACjE,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAChC,OAAO,6BAA6B,SAAS,kBAAkB,CAAA;IACjE,CAAC;IAED,oDAAoD;IACpD,kCAAkC;IAClC,kCAAkC;IAClC,wBAAwB;IACxB,mCAAmC;IAEnC,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,cAAsB,EAAE;IAC1D,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAA;IACzC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAC7B,wCAAwC;IACxC,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;AAClD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YACE,OAAe,EACR,IAAY,EACZ,aAAqB,GAAG;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAA;QAHP,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAc;QAG/B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,IAAY,EACZ,aAAqB,GAAG;IAExB,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,CAAA;AACjD,CAAC"}

package/dist/auth/verify-email.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Email Verification
+ *
+ * Handles email verification flow:
+ * - Token validation and expiration checking
+ * - Marking user's email as verified
+ * - Token cleanup after use
+ * - Resending verification emails
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../database/schema.js';
+/**
+ * Verify user's email address using a verification token
+ *
+ * Validates the token, checks expiration, and marks the user's email as verified.
+ * The token is deleted after successful verification.
+ *
+ * @param db - Kysely database instance
+ * @param token - Email verification token
+ * @returns Verification result with user ID if successful
+ * @throws {AuthError} If token is invalid or expired
+ *
+ * @example
+ * ```ts
+ * const result = await verifyEmail(db, 'abc123...')
+ * if (result.success) {
+ *   console.log('Email verified for user:', result.userId)
+ * }
+ * ```
+ */
+export declare function verifyEmail(db: Kysely<Database>, token: string): Promise<{
+    success: boolean;
+    userId?: string;
+}>;
+/**
+ * Resend verification email
+ *
+ * Generates a new verification token for the user with the given email.
+ * Deletes any existing tokens for that user before creating a new one.
+ *
+ * @param db - Kysely database instance
+ * @param email - User's email address
+ * @returns New verification token
+ * @throws {AuthError} If user not found or email already verified
+ *
+ * @example
+ * ```ts
+ * const { token } = await resendVerificationEmail(db, 'user@example.com')
+ * // Send token to user via email
+ * ```
+ */
+export declare function resendVerificationEmail(db: Kysely<Database>, email: string): Promise<{
+    token: string;
+}>;
+/**
+ * Clean up expired verification tokens
+ *
+ * Removes all expired email verification tokens from the database.
+ * This should be run periodically as a background job.
+ *
+ * @param db - Kysely database instance
+ * @returns Number of tokens deleted
+ *
+ * @example
+ * ```ts
+ * const deleted = await cleanupExpiredVerificationTokens(db)
+ * console.log(`Cleaned up ${deleted} expired verification tokens`)
+ * ```
+ */
+export declare function cleanupExpiredVerificationTokens(db: Kysely<Database>): Promise<number>;

package/dist/auth/verify-email.js

@@ -0,0 +1,137 @@
+/**
+ * Email Verification
+ *
+ * Handles email verification flow:
+ * - Token validation and expiration checking
+ * - Marking user's email as verified
+ * - Token cleanup after use
+ * - Resending verification emails
+ */
+import { generateSecureToken, createAuthError, normalizeEmail } from './utils.js';
+import { isValidEmailVerificationToken } from '../database/schema.js';
+/**
+ * Email verification token expiration (24 hours)
+ */
+const VERIFICATION_TOKEN_EXPIRY = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
+/**
+ * Verify user's email address using a verification token
+ *
+ * Validates the token, checks expiration, and marks the user's email as verified.
+ * The token is deleted after successful verification.
+ *
+ * @param db - Kysely database instance
+ * @param token - Email verification token
+ * @returns Verification result with user ID if successful
+ * @throws {AuthError} If token is invalid or expired
+ *
+ * @example
+ * ```ts
+ * const result = await verifyEmail(db, 'abc123...')
+ * if (result.success) {
+ *   console.log('Email verified for user:', result.userId)
+ * }
+ * ```
+ */
+export async function verifyEmail(db, token) {
+    if (!token || token.trim() === '') {
+        throw createAuthError('Verification token is required', 'INVALID_TOKEN', 400);
+    }
+    // Look up token in database
+    const tokenRecord = await db
+        .selectFrom('email_verification_tokens')
+        .selectAll()
+        .where('token', '=', token)
+        .executeTakeFirst();
+    if (!tokenRecord) {
+        throw createAuthError('Invalid verification token', 'INVALID_TOKEN', 400);
+    }
+    // Check if token is expired
+    if (!isValidEmailVerificationToken(tokenRecord)) {
+        // Delete expired token
+        await db.deleteFrom('email_verification_tokens').where('token', '=', token).execute();
+        throw createAuthError('Verification token has expired', 'TOKEN_EXPIRED', 400);
+    }
+    // Mark user's email as verified
+    await db
+        .updateTable('users')
+        .set({ email_verified: true })
+        .where('id', '=', tokenRecord.user_id)
+        .execute();
+    // Delete used verification token
+    await db.deleteFrom('email_verification_tokens').where('token', '=', token).execute();
+    return {
+        success: true,
+        userId: tokenRecord.user_id,
+    };
+}
+/**
+ * Resend verification email
+ *
+ * Generates a new verification token for the user with the given email.
+ * Deletes any existing tokens for that user before creating a new one.
+ *
+ * @param db - Kysely database instance
+ * @param email - User's email address
+ * @returns New verification token
+ * @throws {AuthError} If user not found or email already verified
+ *
+ * @example
+ * ```ts
+ * const { token } = await resendVerificationEmail(db, 'user@example.com')
+ * // Send token to user via email
+ * ```
+ */
+export async function resendVerificationEmail(db, email) {
+    const normalizedEmail = normalizeEmail(email);
+    // Look up user by email
+    const user = await db
+        .selectFrom('users')
+        .select(['id', 'email', 'email_verified'])
+        .where('email', '=', normalizedEmail)
+        .executeTakeFirst();
+    if (!user) {
+        // Don't reveal whether email exists (security)
+        throw createAuthError('If this email exists, a verification link will be sent', 'EMAIL_SENT', 200);
+    }
+    if (user.email_verified) {
+        throw createAuthError('Email is already verified', 'ALREADY_VERIFIED', 400);
+    }
+    // Delete any existing verification tokens for this user
+    await db.deleteFrom('email_verification_tokens').where('user_id', '=', user.id).execute();
+    // Generate new verification token
+    const verificationToken = generateSecureToken(32); // 256 bits of entropy
+    const expiresAt = new Date(Date.now() + VERIFICATION_TOKEN_EXPIRY);
+    const newToken = {
+        token: verificationToken,
+        user_id: user.id,
+        email: normalizedEmail,
+        expires_at: expiresAt,
+    };
+    await db.insertInto('email_verification_tokens').values(newToken).execute();
+    return {
+        token: verificationToken,
+    };
+}
+/**
+ * Clean up expired verification tokens
+ *
+ * Removes all expired email verification tokens from the database.
+ * This should be run periodically as a background job.
+ *
+ * @param db - Kysely database instance
+ * @returns Number of tokens deleted
+ *
+ * @example
+ * ```ts
+ * const deleted = await cleanupExpiredVerificationTokens(db)
+ * console.log(`Cleaned up ${deleted} expired verification tokens`)
+ * ```
+ */
+export async function cleanupExpiredVerificationTokens(db) {
+    const result = await db
+        .deleteFrom('email_verification_tokens')
+        .where('expires_at', '<=', new Date())
+        .executeTakeFirst();
+    return Number(result.numDeletedRows ?? 0);
+}
+//# sourceMappingURL=verify-email.js.map

package/dist/auth/verify-email.js.map

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

package/dist/createMechAuth.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 { type MechKyselyConfig } from "./mech-kysely.js";
+import type { ClearAuthConfig } from "./types.js";
+/**
+ * Default session configuration
+ * - 7 day expiration
+ * - Secure cookies in production
+ * - SameSite: lax
+ */
+export declare const defaultSessionConfig: {
+    readonly expiresIn: number;
+    readonly cookie: {
+        readonly name: "session";
+        readonly httpOnly: true;
+        readonly sameSite: "lax";
+        readonly path: "/";
+    };
+};
+/**
+ * Short-lived session configuration (for high-security apps)
+ * - 1 hour expiration
+ * - Strict cookies
+ */
+export declare const shortSessionConfig: {
+    readonly expiresIn: number;
+    readonly cookie: {
+        readonly name: "session";
+        readonly httpOnly: true;
+        readonly sameSite: "strict";
+        readonly path: "/";
+    };
+};
+/**
+ * Long-lived session configuration (for consumer apps)
+ * - 30 day expiration
+ * - Lax cookies for better UX
+ */
+export declare const longSessionConfig: {
+    readonly expiresIn: number;
+    readonly cookie: {
+        readonly name: "session";
+        readonly httpOnly: true;
+        readonly sameSite: "lax";
+        readonly path: "/";
+    };
+};
+/**
+ * Simplified database configuration
+ * Only appId and apiKey are required - everything else has smart defaults
+ */
+export type SimpleDatabaseConfig = {
+    /** Mech App ID (required) */
+    appId: string;
+    /** Mech API Key (required) */
+    apiKey: string;
+    /** Base URL for Mech Storage. Defaults to "https://storage.mechdna.net" */
+    baseUrl?: string;
+    /** App Schema ID. Defaults to appId */
+    appSchemaId?: string;
+    /** Request timeout in ms. Defaults to 30000 */
+    timeout?: number;
+    /** Max retry attempts. Defaults to 2 */
+    maxRetries?: number;
+};
+export type CreateClearAuthOptions = {
+    /** Secret key for session signing (required) */
+    secret: string;
+    /**
+     * Database configuration. Can be:
+     * - Simplified: { appId, apiKey } (recommended)
+     * - Full config: { config: MechKyselyConfig }
+     */
+    database: SimpleDatabaseConfig | {
+        config: MechKyselyConfig;
+    };
+    /** Base URL for your application (required for OAuth redirects) */
+    baseUrl: string;
+    /** Set to true if running in production */
+    isProduction?: boolean;
+    /** Session configuration (optional, uses defaults if not provided) */
+    session?: ClearAuthConfig['session'];
+    /** OAuth provider configuration (optional) */
+    oauth?: ClearAuthConfig['oauth'];
+    /** Password validation configuration (optional) */
+    password?: ClearAuthConfig['password'];
+    /** Password hashing implementation (optional) */
+    passwordHasher?: ClearAuthConfig['passwordHasher'];
+};
+/**
+ * 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 declare function createClearAuth(options: CreateClearAuthOptions): ClearAuthConfig;