mulguard 1.0.1

package/dist/core/security/xss.d.ts

@@ -0,0 +1,20 @@
+/**
+ * XSS Protection utilities
+ */
+/**
+ * Escape HTML to prevent XSS
+ */
+export declare function escapeHTML(str: string): string;
+/**
+ * Sanitize HTML (basic)
+ * Note: For production, use a proper HTML sanitizer library like DOMPurify
+ */
+export declare function sanitizeHTML(html: string): string;
+/**
+ * Validate and sanitize user input
+ */
+export declare function sanitizeUserInput(input: unknown): string;
+/**
+ * Check for potential XSS patterns
+ */
+export declare function containsXSSPattern(input: string): boolean;

package/dist/core/session/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session management utilities
+ */
+export interface SessionStorage {
+    get(key: string): string | null;
+    set(key: string, value: string, options?: SessionCookieOptions): void;
+    remove(key: string): void;
+}
+export interface SessionCookieOptions {
+    expires?: Date | number;
+    maxAge?: number;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+}
+/**
+ * Cookie storage implementation (client-side only)
+ * Note: This is for browser environments. Server-side should use Next.js cookies() API
+ */
+export declare class CookieStorage implements SessionStorage {
+    get(key: string): string | null;
+    set(key: string, value: string, options?: SessionCookieOptions): void;
+    remove(key: string): void;
+}
+/**
+ * Memory storage implementation (for testing)
+ */
+export declare class MemoryStorage implements SessionStorage {
+    private storage;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}

package/dist/core/types/auth.d.ts

@@ -0,0 +1,131 @@
+import { AuthErrorCode } from './errors';
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    avatar?: string;
+    roles?: string[];
+    emailVerified?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Session object containing user information and authentication tokens
+ *
+ * @property user - User object with authentication information
+ * @property expiresAt - Session expiration date/time
+ * @property accessToken - Access token for API authentication (optional)
+ * @property refreshToken - Refresh token for token refresh (optional)
+ * @property tokenType - Type of token (default: 'Bearer')
+ * @property expiresIn - Token expiration time in seconds (optional)
+ * @property refreshTokenExpiresAt - Refresh token expiration date/time (optional)
+ */
+export interface Session {
+    user: User;
+    expiresAt: Date | string;
+    /** Access token for API authentication (optional) */
+    accessToken?: string;
+    /** Refresh token for token refresh (optional) */
+    refreshToken?: string;
+    /** Type of token (default: 'Bearer') */
+    tokenType?: 'Bearer' | 'Basic';
+    /** Token expiration time in seconds (optional) */
+    expiresIn?: number;
+    /** Refresh token expiration date/time (optional) */
+    refreshTokenExpiresAt?: Date | string;
+    [key: string]: unknown;
+}
+/**
+ * Authentication result returned by sign-in, sign-up, and other auth actions
+ *
+ * @property success - Whether the authentication was successful
+ * @property user - User object if authentication succeeded
+ * @property session - Session object if authentication succeeded
+ * @property error - Error message if authentication failed
+ * @property errorCode - Specific error code for programmatic error handling
+ * @property requires2FA - Whether 2FA verification is required (true when 2FA is needed)
+ * @property email - Email address (required when requires2FA is true)
+ * @property userId - User ID (required when requires2FA is true)
+ *
+ * @example
+ * ```typescript
+ * const result = await auth.signIn.email({ email: 'user@example.com', password: 'password' })
+ * if (result.success) {
+ *   // Authentication successful
+ *   console.log('User:', result.user)
+ * } else if (result.requires2FA) {
+ *   // 2FA required
+ *   console.log('2FA required for:', result.email)
+ * } else {
+ *   // Authentication failed
+ *   console.error('Error:', result.error, result.errorCode)
+ * }
+ * ```
+ */
+export interface AuthResult {
+    success: boolean;
+    user?: User;
+    session?: Session;
+    error?: string;
+    /** Error code for programmatic error handling */
+    errorCode?: AuthErrorCode;
+    /** Indicates if 2FA is required */
+    requires2FA?: boolean;
+    /** Email for 2FA flow */
+    email?: string;
+    /** User ID for 2FA flow */
+    userId?: string;
+}
+/**
+ * Two-factor authentication result
+ *
+ * This type is returned when 2FA verification is required after initial authentication.
+ * Use the `isTwoFactorRequired()` helper function to check if a result is of this type.
+ *
+ * @property success - Always false for 2FA required results
+ * @property requires2FA - Always true
+ * @property email - Email address of the user requiring 2FA
+ * @property userId - User ID requiring 2FA
+ * @property errorCode - Always AuthErrorCode.TWO_FA_REQUIRED
+ * @property twoFactorMethod - Method of 2FA (totp, sms, email) - optional
+ * @property challengeToken - Challenge token for 2FA verification - optional
+ *
+ * @example
+ * ```typescript
+ * const result = await auth.signIn.email({ email: 'user@example.com', password: 'password' })
+ * if (isTwoFactorRequired(result)) {
+ *   // TypeScript knows result is TwoFactorAuthResult here
+ *   console.log('2FA required for:', result.email)
+ *   console.log('Method:', result.twoFactorMethod) // 'totp' | 'sms' | 'email'
+ * }
+ * ```
+ */
+export interface TwoFactorAuthResult extends AuthResult {
+    success: false;
+    requires2FA: true;
+    email: string;
+    userId: string;
+    error: '2FA_REQUIRED';
+    errorCode: AuthErrorCode.TWO_FA_REQUIRED;
+    /** Method of 2FA (totp, sms, email) - optional */
+    twoFactorMethod?: 'totp' | 'sms' | 'email';
+    /** Challenge token for 2FA verification - optional */
+    challengeToken?: string;
+}
+/**
+ * Data for 2FA verification
+ */
+export interface Verify2FAData {
+    email: string;
+    userId: string;
+    code: string;
+}
+export interface EmailCredentials {
+    email: string;
+    password: string;
+}
+export interface RegisterData {
+    email: string;
+    password: string;
+    name: string;
+    [key: string]: unknown;
+}

package/dist/core/types/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Authentication error codes
+ */
+export declare enum AuthErrorCode {
+    /** Invalid email or password */
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    /** Account is temporarily locked */
+    ACCOUNT_LOCKED = "ACCOUNT_LOCKED",
+    /** Account is inactive or disabled */
+    ACCOUNT_INACTIVE = "ACCOUNT_INACTIVE",
+    /** Two-factor authentication required */
+    TWO_FA_REQUIRED = "TWO_FA_REQUIRED",
+    /** Invalid two-factor authentication code */
+    INVALID_TWO_FA_CODE = "INVALID_TWO_FA_CODE",
+    /** Session has expired */
+    SESSION_EXPIRED = "SESSION_EXPIRED",
+    /** User is not authorized */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** Network or API error */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Validation error */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Rate limit exceeded */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Unknown error */
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Authentication error interface
+ */
+export interface AuthError {
+    /** Error code */
+    code: AuthErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code (if applicable) */
+    statusCode?: number;
+    /** Additional error details */
+    details?: unknown;
+}
+/**
+ * Create an authentication error
+ */
+export declare function createAuthError(code: AuthErrorCode, message: string, statusCode?: number, details?: unknown): AuthError;

package/dist/core/types/index.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Core types for Mulguard Authentication Library
+ * Server Actions-based architecture with custom logic support
+ */
+export * from './auth';
+export * from './errors';
+/**
+ * API Client interface for making HTTP requests
+ * Used internally by some auth methods
+ */
+export interface ApiClient {
+    get: <T>(url: string, config?: unknown) => Promise<{
+        data: T;
+    }>;
+    post: <T>(url: string, data?: unknown, config?: unknown) => Promise<{
+        data: T;
+    }>;
+    put: <T>(url: string, data?: unknown, config?: unknown) => Promise<{
+        data: T;
+    }>;
+    delete: <T>(url: string, config?: unknown) => Promise<{
+        data: T;
+    }>;
+}
+/**
+ * Remembered user for account picker
+ */
+export interface RememberedUser {
+    userId: string;
+    email: string;
+    name: string;
+    avatar?: string;
+    provider: 'email' | 'oauth' | 'passkey';
+    lastLoginAt: Date;
+}
+/**
+ * OAuth Provider Configuration (auth.js-like)
+ * Simple configuration - just clientId and clientSecret
+ */
+export interface OAuthProviderConfig {
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret (server-side only) */
+    clientSecret?: string;
+    /** Custom redirect URI (optional, auto-generated if not provided) */
+    redirectUri?: string;
+    /** Custom scopes (optional, defaults provided) */
+    scopes?: string[];
+    /** Additional parameters */
+    params?: Record<string, string>;
+}
+/**
+ * OAuth Providers Configuration
+ * Simple auth.js-like interface
+ */
+export interface OAuthProvidersConfig {
+    google?: OAuthProviderConfig;
+    github?: OAuthProviderConfig;
+    apple?: OAuthProviderConfig;
+    facebook?: OAuthProviderConfig;
+    [key: string]: OAuthProviderConfig | undefined;
+}
+/**
+ * Main configuration for Mulguard
+ * User provides custom logic for each authentication method
+ */
+export interface MulguardConfig {
+    /** Session configuration */
+    session?: SessionConfig;
+    /** Custom authentication logic - user writes their own implementation */
+    actions: AuthActions;
+    /** Callbacks for lifecycle events */
+    callbacks?: CallbacksConfig;
+    /** Security configuration */
+    security?: SecurityConfig;
+    /** Token refresh configuration */
+    tokenRefresh?: import('../client/token-refresh-manager').TokenRefreshConfig;
+    /** ✅ NEW: OAuth providers configuration (auth.js-like) */
+    providers?: {
+        oauth?: OAuthProvidersConfig;
+    };
+    /** ✅ NEW: OAuth state store (for production, use Redis/database-backed store) */
+    oauthStateStore?: import('../auth/oauth-state-store').OAuthStateStore;
+    /** ✅ NEW: Session cache TTL in milliseconds (default: 5000) */
+    sessionCacheTtl?: number;
+}
+/**
+ * Sign in options for unified signIn interface
+ */
+export type SignInProvider = 'google' | 'github' | 'apple' | 'facebook' | string;
+export interface SignInOptions {
+    provider: SignInProvider | 'credentials' | 'passkey' | 'otp';
+    credentials?: EmailCredentials;
+    formData?: FormData;
+    options?: {
+        userId?: string;
+        email?: string;
+        code?: string;
+    };
+}
+/**
+ * Custom authentication actions - user implements these
+ * All actions are Server Actions that run on the server
+ */
+export interface AuthActions {
+    /**
+     * Sign in actions
+     */
+    signIn: {
+        /**
+         * Email/password sign in
+         * User implements custom logic here
+         */
+        email: (credentials: EmailCredentials) => Promise<AuthResult>;
+        /**
+         * OAuth sign in initiation
+         * Returns authorization URL and state
+         */
+        oauth?: (provider: string) => Promise<{
+            url: string;
+            state: string;
+        }>;
+        /**
+         * PassKey/WebAuthn sign in
+         */
+        passkey?: (options?: {
+            userId?: string;
+        }) => Promise<AuthResult>;
+        /**
+         * OTP sign in
+         */
+        otp?: (email: string, code?: string) => Promise<AuthResult>;
+    };
+    /**
+     * Sign up new user
+     * User implements custom logic here
+     */
+    signUp?: (data: RegisterData) => Promise<AuthResult>;
+    /**
+     * Sign out current session
+     * User implements custom logic here
+     */
+    signOut?: () => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Request password reset
+     * User implements custom logic here
+     */
+    resetPassword?: (email: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Verify email address
+     * User implements custom logic here
+     */
+    verifyEmail?: (token: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get current session
+     * User implements custom logic here
+     */
+    getSession?: () => Promise<Session | null>;
+    /**
+     * Refresh session
+     * User implements custom logic here
+     */
+    refreshSession?: () => Promise<Session | null>;
+    /**
+     * OAuth callback handler
+     * User implements custom logic here
+     */
+    oauthCallback?: (provider: string, code: string, state: string) => Promise<AuthResult>;
+    /**
+     * PassKey methods
+     */
+    passkey?: {
+        register?: (options?: {
+            name?: string;
+            userId?: string;
+        }) => Promise<{
+            success: boolean;
+            passkeyId?: string;
+            error?: string;
+        }>;
+        authenticate?: (options?: {
+            userId?: string;
+        }) => Promise<AuthResult>;
+        list?: () => Promise<Array<{
+            id: string;
+            name: string;
+            createdAt: Date;
+            lastUsedAt?: Date;
+        }>>;
+        remove?: (passKeyId: string) => Promise<{
+            success: boolean;
+            error?: string;
+        }>;
+    };
+    /**
+     * Two-Factor Authentication methods
+     */
+    twoFactor?: {
+        enable?: () => Promise<{
+            success: boolean;
+            qrCode?: string;
+            secret?: string;
+            error?: string;
+        }>;
+        verify?: (code: string) => Promise<{
+            success: boolean;
+            backupCodes?: string[];
+            error?: string;
+        }>;
+        disable?: () => Promise<{
+            success: boolean;
+            error?: string;
+        }>;
+        generateBackupCodes?: () => Promise<{
+            success: boolean;
+            backupCodes?: string[];
+            error?: string;
+        }>;
+        isEnabled?: () => Promise<boolean>;
+        /**
+         * Verify 2FA code after initial sign in
+         * Used when signIn returns requires2FA: true
+         */
+        verify2FA?: (data: import('./auth').Verify2FAData) => Promise<import('./auth').AuthResult>;
+    };
+    /**
+     * Verify 2FA code after initial sign in (legacy - use twoFactor.verify2FA instead)
+     * Used when signIn returns requires2FA: true
+     */
+    verify2FA?: (data: import('./auth').Verify2FAData) => Promise<import('./auth').AuthResult>;
+}
+/**
+ * Session configuration
+ */
+export interface SessionConfig {
+    /** Cookie name (default: '__mulguard_session') */
+    cookieName?: string;
+    /** Session expiration in seconds (default: 7 days) */
+    expiresIn?: number;
+    /** HttpOnly flag (default: true) */
+    httpOnly?: boolean;
+    /** Secure flag (default: true in production) */
+    secure?: boolean;
+    /** SameSite policy (default: 'lax') */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** Cookie path (default: '/') */
+    path?: string;
+    /** Cookie domain (optional) */
+    domain?: string;
+    /** Session cache TTL in milliseconds (default: 5000) */
+    cacheTtl?: number;
+}
+/**
+ * Security configuration
+ */
+export interface SecurityConfig {
+    /** Enable CSRF protection (default: true) */
+    csrfProtection?: boolean;
+    /** Enable rate limiting (default: true) */
+    rateLimiting?: boolean;
+    /** Require HTTPS (default: true in production) */
+    requireHttps?: boolean;
+    /** Allowed origins for CORS */
+    allowedOrigins?: string[];
+}
+/**
+ * OAuth user info from provider
+ */
+export interface OAuthUserInfo {
+    id: string;
+    email: string;
+    name: string;
+    avatar?: string;
+    emailVerified?: boolean;
+}
+/**
+ * Callbacks configuration
+ */
+export interface CallbacksConfig {
+    /** Called after successful sign in */
+    onSignIn?: (user: User, session: Session) => Promise<void> | void;
+    /** Called after sign out */
+    onSignOut?: (user: User) => Promise<void> | void;
+    /** Called when session is updated */
+    onSessionUpdate?: (session: Session) => Promise<Session> | Session;
+    /** Called on error */
+    onError?: (error: Error, context?: string) => Promise<void> | void;
+    /** Called when token is refreshed */
+    onTokenRefresh?: (oldSession: Session, newSession: Session) => Promise<void> | void;
+    /** Called when session expires */
+    onSessionExpired?: (session: Session) => Promise<void> | void;
+    /** ✅ NEW: Called when OAuth user is received (for auto-generated OAuth callback) */
+    onOAuthUser?: (userInfo: OAuthUserInfo, provider: string) => Promise<User>;
+}
+/**
+ * User interface
+ */
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    avatar?: string;
+    roles?: string[];
+    emailVerified?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Session interface
+ */
+export interface Session {
+    user: User;
+    expiresAt: Date | string;
+    [key: string]: unknown;
+}
+/**
+ * Authentication result
+ */
+export interface AuthResult {
+    success: boolean;
+    user?: User;
+    session?: Session;
+    error?: string;
+    /** Error code for programmatic error handling */
+    errorCode?: import('./errors').AuthErrorCode;
+    /** Indicates if 2FA is required */
+    requires2FA?: boolean;
+    /** Email for 2FA flow */
+    email?: string;
+    /** User ID for 2FA flow */
+    userId?: string;
+}
+/**
+ * Email credentials for sign in
+ */
+export interface EmailCredentials {
+    email: string;
+    password: string;
+}
+/**
+ * Registration data
+ */
+export interface RegisterData {
+    email: string;
+    password: string;
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Request context for Server Actions
+ */
+export interface RequestContext {
+    /** Request headers */
+    headers: Headers;
+    /** Request cookies */
+    cookies: Map<string, string>;
+    /** Request IP address */
+    ip?: string;
+    /** Request user agent */
+    userAgent?: string;
+}