mulguard 1.1.6 → 1.1.8

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

@@ -1,48 +0,0 @@
-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

@@ -1,11 +0,0 @@
-/**
- * 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';
-export * from './auth/oauth-state-store-redis';

package/dist/core/mulguard/auth-handlers.d.ts

@@ -1,100 +0,0 @@
-import { AuthResult, EmailCredentials, RegisterData, User, Session, AuthActions, CallbacksConfig } from '../types';
-/**
- * Authentication handlers configuration.
- */
-export interface AuthHandlersConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly actions: AuthActions<TUser, TSession>;
-    readonly callbacks: CallbacksConfig;
-    readonly saveSessionAfterAuth: (result: AuthResult<TUser, TSession>) => Promise<{
-        success: boolean;
-        error?: string;
-        warning?: string;
-    }>;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * Sign-in handlers result.
- */
-export interface SignInHandlers<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly email: (credentials: EmailCredentials) => Promise<AuthResult<TUser, TSession>>;
-    readonly oauth?: (provider: string) => Promise<{
-        url: string;
-        state: string;
-    }>;
-    readonly passkey?: (options?: {
-        userId?: string;
-    }) => Promise<AuthResult<TUser, TSession>>;
-    readonly otp?: (email: string, code?: string) => Promise<AuthResult<TUser, TSession>>;
-}
-/**
- * Creates unified sign-in handler that supports both provider-based and direct method calls.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - Handler configuration
- * @param storeOAuthState - Function to store OAuth state
- * @returns Unified sign-in handler
- */
-export declare function createUnifiedSignInHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: AuthHandlersConfig<TUser, TSession>, storeOAuthState: (state: string, provider: string) => Promise<void>): SignInHandlers<TUser, TSession> & {
-    (provider: string): Promise<{
-        url: string;
-        state: string;
-    }>;
-    (provider: 'credentials', credentials: EmailCredentials): Promise<AuthResult<TUser, TSession>>;
-    (provider: 'otp', options: {
-        email: string;
-        code?: string;
-    }): Promise<AuthResult<TUser, TSession>>;
-    (provider: 'passkey', options?: {
-        userId?: string;
-    }): Promise<AuthResult<TUser, TSession>>;
-};
-/**
- * Creates sign-up handler.
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - Handler configuration
- * @returns Sign-up handler
- */
-export declare function createSignUpHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: AuthHandlersConfig<TUser, TSession>): (data: RegisterData) => Promise<AuthResult<TUser, TSession>>;
-/**
- * TODO: Performance
- * - [ ] Add request deduplication for concurrent sign-in attempts
- * - [ ] Implement rate limiting per email/IP
- * - [ ] Add sign-in attempt caching
- * - [ ] Optimize validation logic
- *
- * TODO: Features
- * - [ ] Add social login account linking
- * - [ ] Implement sign-in with magic link
- * - [ ] Add biometric authentication support
- * - [ ] Create sign-in attempt tracking
- *
- * TODO: Type Safety
- * - [ ] Add runtime validation for all inputs
- * - [ ] Create type-safe credential builders
- * - [ ] Implement compile-time provider validation
- *
- * TODO: Security
- * - [ ] Add CAPTCHA support for repeated failures
- * - [ ] Implement account lockout after failed attempts
- * - [ ] Add device fingerprinting
- * - [ ] Create security event logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive handler tests
- * - [ ] Test all validation scenarios
- * - [ ] Test error handling
- * - [ ] Add integration tests
- *
- * TODO: Documentation
- * - [ ] Document all sign-in methods
- * - [ ] Add usage examples
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] Input validation is basic (consider schema validation)
- * - [ ] No support for custom validation rules
- * - [ ] Error messages may be too generic
- */

package/dist/core/mulguard/defaults.d.ts

@@ -1,58 +0,0 @@
-import { SessionConfig } from '../types';
-import { TokenRefreshConfig } from '../client/token-refresh-manager';
-/**
- * Default session configuration.
- *
- * Auto-detects environment and applies secure defaults.
- *
- * @returns Default session configuration
- */
-export declare function getDefaultSessionConfig(): SessionConfig;
-/**
- * Default token refresh configuration.
- *
- * Optimized to prevent infinite loops and improve performance.
- *
- * @returns Default token refresh configuration
- */
-export declare function getDefaultTokenRefreshConfig(): TokenRefreshConfig;
-/**
- * Gets the base URL for OAuth redirects.
- *
- * Detects the base URL from environment variables or defaults to localhost.
- *
- * @returns Base URL string
- */
-export declare function getBaseUrl(): string;
-/**
- * TODO: Performance
- * - [ ] Cache base URL detection result
- * - [ ] Add configuration validation at startup
- * - [ ] Implement configuration hot-reload support
- *
- * TODO: Features
- * - [ ] Add environment-specific configuration presets
- * - [ ] Create configuration builder pattern
- * - [ ] Add configuration schema validation
- * - [ ] Implement configuration inheritance
- *
- * TODO: Type Safety
- * - [ ] Add type-level validation for configuration values
- * - [ ] Create branded types for configuration
- * - [ ] Implement compile-time configuration checking
- *
- * TODO: Testing
- * - [ ] Add tests for default configurations
- * - [ ] Test environment detection
- * - [ ] Test configuration merging
- *
- * TODO: Documentation
- * - [ ] Document all default values
- * - [ ] Add configuration examples
- * - [ ] Create configuration reference guide
- *
- * TODO: Limitations
- * - [ ] Base URL detection is basic (consider more sophisticated detection)
- * - [ ] No configuration validation at runtime
- * - [ ] Defaults are fixed (consider configurable defaults)
- */

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

@@ -1,9 +0,0 @@
-/**
- * Mulguard core modules.
- *
- * @module @mulguard/core/mulguard
- */
-export * from './defaults';
-export * from './session-manager';
-export * from './auth-handlers';
-export * from './oauth-handler';

package/dist/core/mulguard/oauth-handler.d.ts

@@ -1,93 +0,0 @@
-import { AuthResult, OAuthUserInfo, User, Session, OAuthProviderConfig, OAuthProvidersConfig, CallbacksConfig } from '../types';
-import { exchangeOAuthCode } from '../auth/oauth-providers';
-/**
- * OAuth handler configuration.
- */
-export interface OAuthHandlerConfig<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>> {
-    readonly oauthProviders: OAuthProvidersConfig;
-    readonly baseUrl: string;
-    readonly callbacks: CallbacksConfig;
-    readonly createSession: (user: TUser, userInfo: OAuthUserInfo, tokens: Awaited<ReturnType<typeof exchangeOAuthCode>>) => TSession;
-    readonly saveSession: (session: TSession) => Promise<void>;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * OAuth state validation function.
- */
-export type ValidateOAuthState = (state: string, provider: string) => Promise<boolean>;
-/**
- * Creates OAuth callback handler.
- *
- * Automatically handles:
- * 1. Code exchange for tokens
- * 2. User profile retrieval
- * 3. User creation/lookup via callback
- * 4. Session creation and storage
- *
- * @template TUser - User type
- * @template TSession - Session type
- * @param config - OAuth handler configuration
- * @param validateState - Function to validate OAuth state
- * @returns OAuth callback handler
- *
- * @example
- * ```typescript
- * const handler = createOAuthCallbackHandler(config, validateState)
- * const result = await handler('google', 'code123', 'state456')
- * ```
- */
-export declare function createOAuthCallbackHandler<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(config: OAuthHandlerConfig<TUser, TSession>, _validateState: ValidateOAuthState): (provider: string, code: string, _state: string) => Promise<AuthResult<TUser, TSession>>;
-/**
- * Creates OAuth initiation action if providers are configured.
- *
- * @param oauthProviders - OAuth providers configuration
- * @param baseUrl - Base URL for redirects
- * @param generateState - Function to generate CSRF state
- * @param buildAuthUrl - Function to build authorization URL
- * @returns OAuth initiation action or undefined
- */
-export declare function createOAuthInitiationAction(oauthProviders: OAuthProvidersConfig, baseUrl: string, generateState: () => string, buildAuthUrl: (provider: string, config: OAuthProviderConfig, baseUrl: string, state: string) => string): ((provider: string) => Promise<{
-    url: string;
-    state: string;
-}>) | undefined;
-/**
- * TODO: Performance
- * - [ ] Add token exchange result caching
- * - [ ] Implement request retry logic
- * - [ ] Add connection pooling for OAuth API calls
- * - [ ] Cache user profile data
- *
- * TODO: Features
- * - [ ] Add PKCE support
- * - [ ] Implement token refresh flow
- * - [ ] Add OAuth 2.1 compliance
- * - [ ] Support for OpenID Connect
- * - [ ] Add account linking
- *
- * TODO: Type Safety
- * - [ ] Add type-safe provider configuration
- * - [ ] Create type-level endpoint validation
- * - [ ] Implement compile-time provider validation
- *
- * TODO: Security
- * - [ ] Add token validation before use
- * - [ ] Implement token encryption
- * - [ ] Add request signing
- * - [ ] Create security audit logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive OAuth handler tests
- * - [ ] Test all provider flows
- * - [ ] Test error handling
- * - [ ] Add integration tests
- *
- * TODO: Documentation
- * - [ ] Document OAuth flow
- * - [ ] Add provider setup guides
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] No support for OAuth 1.0
- * - [ ] Token refresh not implemented
- * - [ ] No PKCE support yet
- */

package/dist/core/mulguard/session-manager.d.ts

@@ -1,94 +0,0 @@
-import { Session, SessionConfig } from '../types';
-/**
- * Session cache entry.
- */
-interface SessionCacheEntry {
-    readonly session: Session | null;
-    readonly timestamp: number;
-}
-/**
- * Session manager configuration.
- */
-export interface SessionManagerConfig {
-    readonly sessionConfig: SessionConfig;
-    readonly cacheTtl: number;
-    readonly getSessionAction?: () => Promise<Session | null>;
-    readonly onSessionExpired?: (session: Session) => Promise<void> | void;
-    readonly onError?: (error: Error, context: string) => Promise<void> | void;
-}
-/**
- * Session operation result.
- */
-export interface SessionResult {
-    readonly success: boolean;
-    readonly error?: string;
-    readonly warning?: string;
-}
-/**
- * Creates a session manager instance.
- *
- * @param config - Session manager configuration
- * @returns Session manager functions
- */
-export declare function createSessionManager(config: SessionManagerConfig): {
-    getSession: () => Promise<Session | null>;
-    setSession: (session: Session) => Promise<SessionResult>;
-    clearSessionCookie: () => Promise<void>;
-    getAccessToken: () => Promise<string | null>;
-    getRefreshToken: () => Promise<string | null>;
-    hasValidTokens: () => Promise<boolean>;
-    clearCache: () => void;
-    getSessionConfig: () => {
-        cookieName: string;
-        config: SessionConfig;
-    };
-};
-/**
- * Type predicate to check if a value is a valid session cache entry.
- *
- * @param value - Value to check
- * @returns True if value is a valid cache entry
- */
-export declare function isSessionCacheEntry(value: unknown): value is SessionCacheEntry;
-export {};
-/**
- * TODO: Performance
- * - [ ] Add session compression for large sessions
- * - [ ] Implement session chunking for very large sessions
- * - [ ] Add session cache invalidation strategies
- * - [ ] Consider using WeakMap for session references
- *
- * TODO: Features
- * - [ ] Add session encryption at rest
- * - [ ] Implement session rotation
- * - [ ] Add session fingerprinting
- * - [ ] Create session analytics
- * - [ ] Add session migration support
- *
- * TODO: Type Safety
- * - [ ] Add type-level session validation
- * - [ ] Create type-safe session builders
- * - [ ] Implement session schema validation
- *
- * TODO: Security
- * - [ ] Add session hijacking detection
- * - [ ] Implement session timeout warnings
- * - [ ] Add session audit logging
- * - [ ] Create session security monitoring
- *
- * TODO: Testing
- * - [ ] Add comprehensive session manager tests
- * - [ ] Test cache invalidation
- * - [ ] Test session expiration
- * - [ ] Test error handling
- *
- * TODO: Documentation
- * - [ ] Document session lifecycle
- * - [ ] Add session best practices guide
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] Session cache is in-memory (not shared across instances)
- * - [ ] No session persistence (consider database-backed sessions)
- * - [ ] Session validation is basic (consider schema validation)
- */

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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1,132 +0,0 @@
-/**
- * Security utilities for Mulguard Authentication Library.
- *
- * Provides token generation, CSRF protection, input sanitization, and validation.
- *
- * @module @mulguard/core/security
- */
-/**
- * Generates a cryptographically secure random token.
- *
- * @param length - Token length in bytes (default: 32)
- * @returns Base64url-encoded token
- *
- * @example
- * ```typescript
- * const token = generateToken(32)
- * // Returns: 'abc123xyz...' (base64url encoded)
- * ```
- */
-export declare function generateToken(length?: number): string;
-/**
- * Generates a CSRF token for state validation.
- *
- * @returns Base64url-encoded CSRF token
- *
- * @example
- * ```typescript
- * const state = generateCSRFToken()
- * // Store state for validation
- * ```
- */
-export declare function generateCSRFToken(): string;
-/**
- * Validates a CSRF token using constant-time comparison.
- *
- * Uses constant-time comparison to prevent timing attacks.
- *
- * @param token - Token to validate
- * @param expected - Expected token value
- * @returns True if tokens match
- *
- * @example
- * ```typescript
- * const isValid = validateCSRFToken(receivedToken, storedToken)
- * if (!isValid) {
- *   throw new Error('Invalid CSRF token')
- * }
- * ```
- */
-export declare function validateCSRFToken(token: unknown, expected: unknown): boolean;
-/**
- * Type predicate to check if CSRF token is valid.
- *
- * @param token - Token to check
- * @param expected - Expected token
- * @returns True if token is valid
- */
-export declare function isValidCSRFToken(token: unknown, expected: unknown): token is string;
-/**
- * Sanitizes string input by trimming and removing dangerous characters.
- *
- * @param input - Input to sanitize
- * @returns Sanitized string
- *
- * @example
- * ```typescript
- * const sanitized = sanitizeInput('  <script>alert("xss")</script>  ')
- * // Returns: 'scriptalert("xss")script'
- * ```
- */
-export declare function sanitizeInput(input: unknown): string;
-/**
- * Validates email format.
- *
- * @param email - Email to validate
- * @returns True if email is valid
- *
- * @example
- * ```typescript
- * if (isValidEmail('user@example.com')) {
- *   // Email is valid
- * }
- * ```
- */
-export declare function isValidEmail(email: unknown): email is string;
-export * from './rate-limit';
-export * from './headers';
-export * from './validation';
-export * from './csrf';
-export * from './xss';
-/**
- * TODO: Performance
- * - [ ] Add token generation caching for high-frequency operations
- * - [ ] Optimize constant-time comparison for very long tokens
- * - [ ] Consider using Web Crypto API for token generation
- * - [ ] Add input sanitization result caching
- *
- * TODO: Features
- * - [ ] Add token expiration validation
- * - [ ] Implement token rotation support
- * - [ ] Add rate limiting for token generation
- * - [ ] Create token strength scoring
- * - [ ] Add token format validation helpers
- *
- * TODO: Type Safety
- * - [ ] Add branded types for tokens
- * - [ ] Create type-safe token validation
- * - [ ] Add type guards for all security functions
- * - [ ] Implement type-level security constraints
- *
- * TODO: Security
- * - [ ] Add token generation logging (with masking)
- * - [ ] Implement token blacklisting
- * - [ ] Add security event monitoring
- * - [ ] Create security audit logging
- *
- * TODO: Testing
- * - [ ] Add comprehensive security tests
- * - [ ] Test timing attack resistance
- * - [ ] Test token generation randomness
- * - [ ] Add fuzzing tests
- *
- * TODO: Documentation
- * - [ ] Document security best practices
- * - [ ] Add security considerations guide
- * - [ ] Document token lifecycle
- *
- * TODO: Limitations
- * - [ ] Token generation uses Node.js Buffer (consider Web Crypto API for browsers)
- * - [ ] Constant-time comparison may have micro-optimizations
- * - [ ] Email validation is basic (use validation.ts for comprehensive validation)
- */

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

@@ -1,39 +0,0 @@
-/**
- * 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;