mulguard 1.0.1

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

@@ -0,0 +1,40 @@
+import { EmailCredentials, RegisterData, AuthResult, ApiClient } from '../types';
+import { OAuthMethods } from './oauth';
+import { PassKeyMethods } from './passkey';
+import { TwoFactorMethods } from './two-factor';
+import { AccountPickerMethods } from '../account-picker';
+export interface AuthMethods {
+    signIn: {
+        email(credentials: EmailCredentials): Promise<AuthResult>;
+        oauth(provider: string): Promise<{
+            url: string;
+            state: string;
+        }>;
+        passkey(options?: {
+            userId?: string;
+        }): Promise<AuthResult>;
+    };
+    signUp(data: RegisterData): Promise<AuthResult>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    verifyEmail(token: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    oauth: OAuthMethods;
+    passkey: PassKeyMethods;
+    twoFactor: TwoFactorMethods;
+    accountPicker: AccountPickerMethods;
+}
+/**
+ * Create authentication methods
+ */
+export declare function createAuthMethods(client: ApiClient, oauthProviders?: Record<string, {
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+    name?: string;
+}>, accountPickerConfig?: import('../account-picker').AccountPickerConfig): AuthMethods;

package/dist/core/auth/oauth-providers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Built-in OAuth Provider Configurations
+ * Simple auth.js-like configuration for OAuth providers
+ */
+/**
+ * OAuth Provider Configuration (auth.js-like)
+ */
+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;
+}
+/**
+ * Provider metadata for built-in providers
+ */
+interface ProviderMetadata {
+    authorizationUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    defaultScopes: string[];
+    defaultParams?: Record<string, string>;
+}
+/**
+ * Get provider metadata
+ */
+export declare function getProviderMetadata(providerId: string): ProviderMetadata | null;
+/**
+ * Build OAuth authorization URL
+ */
+export declare function buildOAuthAuthorizationUrl(providerId: string, config: OAuthProviderConfig, baseUrl: string, state: string): string;
+/**
+ * Exchange authorization code for tokens
+ */
+export declare function exchangeOAuthCode(providerId: string, config: OAuthProviderConfig, code: string, redirectUri: string): Promise<{
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type?: string;
+    id_token?: string;
+}>;
+/**
+ * Get user info from OAuth provider
+ */
+export declare function getOAuthUserInfo(providerId: string, accessToken: string): Promise<{
+    id: string;
+    email: string;
+    name: string;
+    avatar?: string;
+    emailVerified?: boolean;
+}>;
+export {};

package/dist/core/auth/oauth-state-store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OAuth State Store Interface
+ * Allows pluggable state storage for OAuth CSRF protection
+ *
+ * Default implementation uses in-memory Map (for development)
+ * Production should use Redis, database, or other persistent store
+ */
+export interface OAuthState {
+    provider: string;
+    expiresAt: number;
+}
+export interface OAuthStateStore {
+    /**
+     * Store OAuth state with TTL
+     */
+    set(state: string, data: OAuthState, ttl: number): Promise<void> | void;
+    /**
+     * Get OAuth state
+     */
+    get(state: string): Promise<OAuthState | null> | OAuthState | null;
+    /**
+     * Delete OAuth state
+     */
+    delete(state: string): Promise<void> | void;
+    /**
+     * Cleanup expired states (optional, for periodic cleanup)
+     */
+    cleanup?(): Promise<void> | void;
+}
+/**
+ * In-memory OAuth state store (default, for development)
+ * ⚠️ Not suitable for production with multiple server instances
+ */
+export declare class MemoryOAuthStateStore implements OAuthStateStore {
+    private states;
+    set(state: string, data: OAuthState, _ttl: number): void;
+    get(state: string): OAuthState | null;
+    delete(state: string): void;
+    cleanup(): void;
+}
+/**
+ * Create default in-memory OAuth state store
+ */
+export declare function createMemoryOAuthStateStore(): OAuthStateStore;

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

@@ -0,0 +1,20 @@
+import { ApiClient, AuthResult } from '../types';
+export interface OAuthProvider {
+    id: string;
+    name: string;
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+}
+export interface OAuthMethods {
+    initiate(provider: string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    handleCallback(provider: string, code: string, state: string): Promise<AuthResult>;
+    getProviders(): Promise<OAuthProvider[]>;
+}
+/**
+ * Create OAuth methods
+ */
+export declare function createOAuthMethods(client: ApiClient, providers: Record<string, OAuthProvider>): OAuthMethods;

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

@@ -0,0 +1,35 @@
+import { ApiClient, AuthResult } from '../types';
+export interface PassKeyCredential {
+    id: string;
+    name: string;
+    createdAt: Date;
+    lastUsedAt?: Date;
+}
+export interface PassKeyRegisterOptions {
+    name?: string;
+    userId?: string;
+}
+export interface PassKeyAuthOptions {
+    userId?: string;
+}
+export interface PassKeyMethods {
+    register(options?: PassKeyRegisterOptions): Promise<{
+        success: boolean;
+        passkeyId?: string;
+        error?: string;
+    }>;
+    authenticate(options?: PassKeyAuthOptions): Promise<AuthResult>;
+    list(): Promise<PassKeyCredential[]>;
+    remove(passKeyId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Check if WebAuthn is supported
+ */
+export declare function isWebAuthnSupported(): boolean;
+/**
+ * Create PassKey methods
+ */
+export declare function createPassKeyMethods(client: ApiClient): PassKeyMethods;

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

@@ -0,0 +1,22 @@
+/**
+ * Password validation and utilities
+ */
+/**
+ * Validate password strength
+ */
+export interface PasswordValidationResult {
+    valid: boolean;
+    errors: string[];
+    strength: 'weak' | 'medium' | 'strong';
+}
+export interface PasswordPolicy {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSpecialChars?: boolean;
+}
+/**
+ * Validate password against policy
+ */
+export declare function validatePassword(password: string, policy?: PasswordPolicy): PasswordValidationResult;

package/dist/core/auth/signin-unified.d.ts

@@ -0,0 +1,33 @@
+import { MulguardInstance } from '../../mulguard';
+import { EmailCredentials, AuthResult } from '../types';
+/**
+ * Unified sign in function - professional interface similar to auth.js
+ *
+ * @example
+ * ```typescript
+ * // OAuth providers
+ * await signIn(auth, 'google')
+ * await signIn(auth, 'github')
+ *
+ * // Credentials
+ * await signIn(auth, 'credentials', { email: 'user@example.com', password: 'password' })
+ *
+ * // OTP
+ * await signIn(auth, 'otp', { email: 'user@example.com', code: '123456' })
+ *
+ * // Passkey
+ * await signIn(auth, 'passkey', { userId: 'user-id' })
+ * ```
+ */
+export declare function signIn(auth: MulguardInstance, provider: 'google' | 'github' | 'apple' | 'facebook' | string): Promise<{
+    url: string;
+    state: string;
+}>;
+export declare function signIn(auth: MulguardInstance, provider: 'credentials', credentials: EmailCredentials): Promise<AuthResult>;
+export declare function signIn(auth: MulguardInstance, provider: 'otp', options: {
+    email: string;
+    code?: string;
+}): Promise<AuthResult>;
+export declare function signIn(auth: MulguardInstance, provider: 'passkey', options?: {
+    userId?: string;
+}): Promise<AuthResult>;

package/dist/core/auth/two-factor.d.ts

@@ -0,0 +1,28 @@
+import { ApiClient } from '../types';
+export interface TwoFactorMethods {
+    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>;
+}
+/**
+ * Create 2FA methods
+ */
+export declare function createTwoFactorMethods(client: ApiClient): TwoFactorMethods;

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

@@ -0,0 +1,132 @@
+/**
+ * HTTP Client for making requests to backend API
+ * Enhanced with timeout enforcement, retry logic, and interceptors
+ */
+export interface HttpClientConfig {
+    baseURL: string;
+    apiPrefix: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    retry?: RetryConfig;
+    interceptors?: InterceptorsConfig;
+    /** Token refresh manager for automatic token refresh on 401 errors */
+    tokenRefreshManager?: import('./token-refresh-manager').TokenRefreshManager;
+}
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Exponential backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** HTTP status codes that should trigger retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryableStatusCodes?: number[];
+    /** Whether to retry on network errors (default: true) */
+    retryOnNetworkError?: boolean;
+}
+export interface InterceptorsConfig {
+    /** Request interceptor - called before sending request */
+    onRequest?: (config: RequestConfig) => Promise<RequestConfig> | RequestConfig;
+    /** Response interceptor - called after receiving response */
+    onResponse?: <T>(response: HttpResponse<T>) => Promise<HttpResponse<T>> | HttpResponse<T>;
+    /** Error interceptor - called on error */
+    onError?: (error: ApiError) => Promise<ApiError> | ApiError;
+}
+export interface RequestConfig {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    credentials?: 'include' | 'omit' | 'same-origin';
+}
+interface InternalRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string>;
+    body?: unknown;
+    credentials?: 'include' | 'omit' | 'same-origin';
+    skipRetry?: boolean;
+    skipInterceptors?: boolean;
+    skipTokenRefresh?: boolean;
+}
+export interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Headers;
+}
+export declare class HttpClient {
+    private config;
+    private pendingRequests;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make HTTP request with timeout, retry, and interceptors
+     */
+    request<T = unknown>(path: string, options?: InternalRequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Execute HTTP request with retry logic
+     */
+    private executeRequest;
+    /**
+     * Check if request should be retried
+     */
+    private shouldRetry;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep utility for retry delays
+     */
+    private sleep;
+    /**
+     * Build RequestInit from RequestConfig
+     */
+    private buildRequestInitFromConfig;
+    /**
+     * GET request
+     */
+    get<T = unknown>(path: string, options?: Omit<InternalRequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>>;
+    /**
+     * POST request
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: Omit<InternalRequestOptions, 'method'>): Promise<HttpResponse<T>>;
+    /**
+     * PUT request
+     */
+    put<T = unknown>(path: string, body?: unknown, options?: Omit<InternalRequestOptions, 'method'>): Promise<HttpResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T = unknown>(path: string, options?: Omit<InternalRequestOptions, 'method' | 'body'>): Promise<HttpResponse<T>>;
+    /**
+     * Build full URL
+     */
+    private buildUrl;
+    /**
+     * Parse response
+     */
+    private parseResponse;
+    /**
+     * Handle error response
+     */
+    private handleErrorResponse;
+}
+/**
+ * API Error class with enhanced error information
+ */
+export declare class ApiError extends Error {
+    code: string;
+    statusCode: number;
+    originalError?: Error;
+    retryable?: boolean;
+    constructor(message: string, code?: string, statusCode?: number, originalError?: Error, retryable?: boolean);
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Get user-friendly error message
+     */
+    getUserMessage(): string;
+}
+export {};

package/dist/core/client/token-refresh-manager.d.ts

@@ -0,0 +1,48 @@
+import { Session } from '../types';
+export interface TokenRefreshConfig {
+    /** Enable/disable automatic token refresh */
+    enabled?: boolean;
+    /** Time before token expiration to refresh (in seconds) */
+    refreshThreshold?: number;
+    /** Maximum number of refresh retries on failure */
+    maxRetries?: number;
+    /** Delay between retries (milliseconds) */
+    retryDelay?: number;
+    /** Maximum refresh requests per minute */
+    rateLimit?: number;
+    /** Enable/disable auto sign-out on refresh failure */
+    autoSignOutOnFailure?: boolean;
+    /** Login page URL for redirect on failure */
+    redirectToLogin?: string;
+    /** Enable/disable auto redirect on failure */
+    autoRedirectOnFailure?: boolean;
+    /** Callback on successful token refresh */
+    onTokenRefreshed?: (session: Session) => void | Promise<void>;
+    /** Callback on token refresh failure (before sign-out) */
+    onTokenRefreshFailed?: (error: Error) => void | Promise<void>;
+    /** Callback before redirect (can return false to cancel redirect) */
+    onBeforeRedirect?: (error: Error) => boolean | Promise<boolean>;
+}
+export interface TokenRefreshManager {
+    /** Refresh token with single refresh queue */
+    refreshToken(): Promise<Session | null>;
+    /** Check if refresh is in progress */
+    isRefreshing(): boolean;
+    /** Wait for current refresh to complete */
+    waitForRefresh(): Promise<Session | null>;
+    /** Clear state (on sign-out) */
+    clear(): void;
+    /** Handle token refresh failure */
+    handleRefreshFailure(error: Error): Promise<void>;
+}
+type RefreshFunction = () => Promise<Session | null>;
+type SignOutFunction = () => Promise<{
+    success: boolean;
+    error?: string;
+}>;
+type ClearSessionFunction = () => Promise<void>;
+/**
+ * Create Token Refresh Manager
+ */
+export declare function createTokenRefreshManager(refreshFn: RefreshFunction, signOutFn: SignOutFunction, clearSessionFn: ClearSessionFunction, config?: TokenRefreshConfig): TokenRefreshManager;
+export {};

package/dist/core/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core authentication library - framework agnostic
+ * Part of mulguard package
+ */
+export type { MulguardConfig, SessionConfig, SecurityConfig, CallbacksConfig, AuthActions, Session, User, AuthResult, EmailCredentials, RegisterData, RequestContext, } from './types';
+export * from './security';
+export * from './utils/auth-helpers';
+export * from './auth/signin-unified';
+export * from './auth/oauth-providers';
+export * from './auth/oauth-state-store';

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

@@ -0,0 +1,46 @@
+/**
+ * CSRF Protection utilities
+ */
+export interface CSRFTokenStore {
+    get(key: string): string | null;
+    set(key: string, value: string, expiresIn?: number): void;
+    delete(key: string): void;
+}
+/**
+ * In-memory CSRF token store (for server-side)
+ */
+export declare class MemoryCSRFStore implements CSRFTokenStore {
+    private tokens;
+    get(key: string): string | null;
+    set(key: string, value: string, expiresIn?: number): void;
+    delete(key: string): void;
+    clear(): void;
+}
+/**
+ * CSRF Protection manager
+ */
+export declare class CSRFProtection {
+    private store;
+    private tokenLength;
+    constructor(store?: CSRFTokenStore, tokenLength?: number);
+    /**
+     * Generate CSRF token
+     */
+    generateToken(key: string, expiresIn?: number): string;
+    /**
+     * Validate CSRF token
+     */
+    validateToken(key: string, token: string): boolean;
+    /**
+     * Get stored token without validating
+     */
+    getToken(key: string): string | null;
+    /**
+     * Delete token
+     */
+    deleteToken(key: string): void;
+}
+/**
+ * Create CSRF protection instance
+ */
+export declare function createCSRFProtection(store?: CSRFTokenStore): CSRFProtection;

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

@@ -0,0 +1,24 @@
+/**
+ * Security Headers utilities
+ */
+export interface SecurityHeaders {
+    'X-Content-Type-Options'?: string;
+    'X-Frame-Options'?: string;
+    'X-XSS-Protection'?: string;
+    'Strict-Transport-Security'?: string;
+    'Content-Security-Policy'?: string;
+    'Referrer-Policy'?: string;
+    'Permissions-Policy'?: string;
+}
+/**
+ * Default security headers
+ */
+export declare const DEFAULT_SECURITY_HEADERS: SecurityHeaders;
+/**
+ * Get security headers
+ */
+export declare function getSecurityHeaders(custom?: Partial<SecurityHeaders>): SecurityHeaders;
+/**
+ * Apply security headers to response
+ */
+export declare function applySecurityHeaders(headers: Headers, custom?: Partial<SecurityHeaders>): void;

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

@@ -0,0 +1,28 @@
+/**
+ * Security utilities
+ */
+/**
+ * Generate random token
+ */
+export declare function generateToken(length?: number): string;
+/**
+ * Generate CSRF token
+ */
+export declare function generateCSRFToken(): string;
+/**
+ * Validate CSRF token (constant-time comparison)
+ */
+export declare function validateCSRFToken(token: string, expected: string): boolean;
+/**
+ * Sanitize string input
+ */
+export declare function sanitizeInput(input: string): string;
+/**
+ * Validate email format
+ */
+export declare function isValidEmail(email: string): boolean;
+export * from './rate-limit';
+export * from './headers';
+export * from './validation';
+export * from './csrf';
+export * from './xss';

package/dist/core/security/rate-limit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Rate Limiting utilities
+ * Client-side rate limiting helpers (actual rate limiting should be on backend)
+ */
+export interface RateLimitConfig {
+    maxAttempts: number;
+    windowMs: number;
+    keyPrefix?: string;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: Date;
+}
+/**
+ * Client-side rate limit tracker
+ * Note: This is just a helper. Real rate limiting must be enforced on the backend.
+ */
+export declare class RateLimiter {
+    private attempts;
+    private config;
+    constructor(config: RateLimitConfig);
+    /**
+     * Check if request is allowed
+     */
+    check(key: string): RateLimitResult;
+    /**
+     * Reset rate limit for a key
+     */
+    reset(key: string): void;
+    /**
+     * Clear all rate limits
+     */
+    clear(): void;
+}
+/**
+ * Create rate limiter instance
+ */
+export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;

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

@@ -0,0 +1,53 @@
+/**
+ * Input validation utilities
+ */
+/**
+ * Validate and sanitize email
+ */
+export declare function validateAndSanitizeEmail(email: string): {
+    valid: boolean;
+    sanitized?: string;
+    error?: string;
+};
+/**
+ * Validate and sanitize password with enhanced security checks
+ */
+export declare function validateAndSanitizePassword(password: string, minLength?: number): {
+    valid: boolean;
+    error?: string;
+    strength?: 'weak' | 'medium' | 'strong';
+};
+/**
+ * Validate and sanitize name
+ */
+export declare function validateAndSanitizeName(name: string): {
+    valid: boolean;
+    sanitized?: string;
+    error?: string;
+};
+/**
+ * Validate URL
+ */
+export declare function validateURL(url: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate token format with enhanced security checks
+ */
+export declare function validateToken(token: string, minLength?: number): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate and sanitize input with XSS prevention
+ */
+export declare function validateAndSanitizeInput(input: string, options?: {
+    maxLength?: number;
+    allowHtml?: boolean;
+    required?: boolean;
+}): {
+    valid: boolean;
+    sanitized?: string;
+    error?: string;
+};