mulguard 1.1.6 → 1.1.8

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

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

@@ -1,197 +0,0 @@
-import { OAuthProviderConfig } from '../types';
-/**
- * OAuth provider identifier.
- */
-export type OAuthProviderId = 'google' | 'github' | 'apple' | 'facebook' | string;
-/**
- * Provider metadata for OAuth endpoints and configuration.
- */
-export interface ProviderMetadata {
-    readonly authorizationUrl: string;
-    readonly tokenUrl: string;
-    readonly userInfoUrl: string;
-    readonly defaultScopes: readonly string[];
-    readonly defaultParams?: Readonly<Record<string, string>>;
-}
-/**
- * Normalized OAuth user profile.
- */
-export interface OAuthUserProfile {
-    readonly id: string;
-    readonly email: string;
-    readonly name: string;
-    readonly avatar?: string;
-    readonly emailVerified?: boolean;
-    readonly rawProfile: Readonly<Record<string, unknown>>;
-}
-/**
- * OAuth token exchange result.
- */
-export interface TokenExchangeResult {
-    readonly access_token: string;
-    readonly refresh_token?: string;
-    readonly expires_in?: number;
-    readonly token_type?: string;
-    readonly id_token?: string;
-    readonly scope?: string;
-}
-/**
- * OAuth error response.
- */
-export interface OAuthErrorResponse {
-    readonly error: string;
-    readonly error_description?: string;
-    readonly error_uri?: string;
-}
-/**
- * Built-in OAuth provider metadata.
- *
- * Contains endpoint URLs, default scopes, and provider-specific parameters.
- */
-declare const PROVIDER_METADATA: Readonly<Record<string, ProviderMetadata>>;
-/**
- * Gets provider metadata for a given provider ID.
- *
- * @param providerId - OAuth provider identifier
- * @returns Provider metadata or null if not found
- *
- * @example
- * ```typescript
- * const metadata = getProviderMetadata('google')
- * if (metadata) {
- *   console.log(metadata.authorizationUrl)
- * }
- * ```
- */
-export declare function getProviderMetadata(providerId: string): ProviderMetadata | null;
-/**
- * Type predicate to check if provider metadata exists.
- *
- * @param providerId - Provider ID to check
- * @returns True if provider is supported
- *
- * @example
- * ```typescript
- * if (isSupportedProvider('google')) {
- *   // Provider is supported
- * }
- * ```
- */
-export declare function isSupportedProvider(providerId: string): providerId is keyof typeof PROVIDER_METADATA;
-/**
- * Builds OAuth authorization URL with proper parameters.
- *
- * @param providerId - OAuth provider identifier
- * @param config - Provider configuration
- * @param baseUrl - Base URL for redirect URI
- * @param state - CSRF state token
- * @returns Authorization URL
- * @throws {Error} If provider is not supported
- *
- * @example
- * ```typescript
- * const url = buildOAuthAuthorizationUrl(
- *   'google',
- *   { clientId: '...' },
- *   'https://example.com',
- *   'state123'
- * )
- * ```
- */
-export declare function buildOAuthAuthorizationUrl(providerId: string, config: OAuthProviderConfig, baseUrl: string, state: string): string;
-/**
- * Exchanges authorization code for access tokens.
- *
- * @param providerId - OAuth provider identifier
- * @param config - Provider configuration
- * @param code - Authorization code from OAuth callback
- * @param redirectUri - Redirect URI used in authorization request
- * @returns Token exchange result
- * @throws {Error} If exchange fails or provider is not supported
- *
- * @example
- * ```typescript
- * const tokens = await exchangeOAuthCode(
- *   'google',
- *   { clientId: '...', clientSecret: '...' },
- *   'code123',
- *   'https://example.com/callback'
- * )
- * console.log(tokens.access_token)
- * ```
- */
-export declare function exchangeOAuthCode(providerId: string, config: OAuthProviderConfig, code: string, redirectUri: string): Promise<TokenExchangeResult>;
-/**
- * Retrieves user information from OAuth provider.
- *
- * @param providerId - OAuth provider identifier
- * @param accessToken - OAuth access token
- * @returns Normalized user profile with raw provider data
- * @throws {Error} If retrieval fails or provider is not supported
- *
- * @example
- * ```typescript
- * const profile = await getOAuthUserInfo('google', 'access_token_123')
- * console.log(profile.email, profile.name)
- * ```
- */
-export declare function getOAuthUserInfo(providerId: string, accessToken: string): Promise<OAuthUserProfile>;
-/**
- * Type predicate to check if a value is a valid OAuth provider config.
- *
- * @param value - Value to check
- * @returns True if value is a valid OAuth provider config
- */
-export declare function isOAuthProviderConfig(value: unknown): value is OAuthProviderConfig;
-export {};
-/**
- * TODO: Performance
- * - [ ] Add token exchange result caching (with TTL)
- * - [ ] Implement request retry logic with exponential backoff
- * - [ ] Add connection pooling for OAuth API calls
- * - [ ] Cache provider metadata lookups
- *
- * TODO: Features
- * - [ ] Add support for PKCE (Proof Key for Code Exchange)
- * - [ ] Implement token refresh flow
- * - [ ] Add support for custom OAuth providers
- * - [ ] Create provider plugin system
- * - [ ] Add OAuth 2.1 compliance
- * - [ ] Support for OpenID Connect
- *
- * TODO: Type Safety
- * - [ ] Add branded types for provider IDs
- * - [ ] Create type-safe provider configuration
- * - [ ] Add compile-time provider validation
- * - [ ] Implement type-level endpoint validation
- *
- * TODO: Security
- * - [ ] Add token validation before use
- * - [ ] Implement token encryption at rest
- * - [ ] Add request signing for OAuth calls
- * - [ ] Create security audit logging
- * - [ ] Add rate limiting for OAuth operations
- *
- * TODO: Error Handling
- * - [ ] Add structured error types for OAuth errors
- * - [ ] Implement error recovery strategies
- * - [ ] Add error retry logic
- * - [ ] Create error reporting
- *
- * TODO: Testing
- * - [ ] Add comprehensive unit tests
- * - [ ] Test all provider normalizations
- * - [ ] Test error handling scenarios
- * - [ ] Add integration tests with mock OAuth servers
- *
- * TODO: Documentation
- * - [ ] Add provider-specific configuration guides
- * - [ ] Document error handling best practices
- * - [ ] Create troubleshooting guide
- *
- * TODO: Limitations
- * - [ ] GitHub email retrieval may fail silently
- * - [ ] Apple profile name only available on first sign-in
- * - [ ] Facebook API version is hardcoded (v18.0)
- * - [ ] No support for OAuth 1.0 providers
- */

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

@@ -1,83 +0,0 @@
-import { OAuthStateStore } from './oauth-state-store';
-/**
- * Cookie options interface
- */
-export interface CookieOptions {
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: 'strict' | 'lax' | 'none';
-    maxAge?: number;
-    path?: string;
-    domain?: string;
-}
-/**
- * Cookie handler interface for framework-agnostic cookie operations
- */
-export interface CookieHandler {
-    /**
-     * Get cookie value by name
-     */
-    getCookie(name: string): Promise<string | null> | string | null;
-    /**
-     * Set cookie with options
-     */
-    setCookie(name: string, value: string, options: CookieOptions): Promise<void> | void;
-    /**
-     * Delete cookie
-     */
-    deleteCookie(name: string, options?: {
-        path?: string;
-    }): Promise<void> | void;
-}
-/**
- * Configuration for cookie-based OAuth state store
- */
-export interface CookieOAuthStateStoreConfig {
-    /**
-     * Cookie handler implementation
-     */
-    cookieHandler: CookieHandler;
-    /**
-     * Cookie name (default: '__mulguard_oauth_state')
-     */
-    cookieName?: string;
-    /**
-     * TTL in milliseconds (default: 10 minutes)
-     */
-    ttl?: number;
-    /**
-     * Whether to use secure cookies (default: true in production)
-     */
-    secure?: boolean;
-    /**
-     * SameSite cookie attribute (default: 'strict')
-     */
-    sameSite?: 'strict' | 'lax' | 'none';
-}
-/**
- * Creates a cookie-based OAuth state store.
- *
- * ✅ SECURE: Uses httpOnly cookies to prevent XSS attacks
- * ✅ FRAMEWORK-AGNOSTIC: Works with any framework via cookie handler
- * ⚠️ LIMITATION: Not suitable for production with multiple server instances (use Redis instead)
- *
- * @param config - Cookie store configuration
- * @returns OAuth state store implementation
- */
-export declare function createCookieOAuthStateStore(config: CookieOAuthStateStoreConfig): OAuthStateStore;
-/**
- * Creates a Next.js-specific cookie-based OAuth state store.
- *
- * Convenience function for Next.js applications.
- *
- * @example
- * ```typescript
- * import { createNextJsCookieOAuthStateStore } from 'mulguard/core/auth/oauth-state-store-cookie'
- *
- * export const auth = mulguard({
- *   oauthStateStore: createNextJsCookieOAuthStateStore(),
- *   // ... rest of config
- * })
- * ```
- */
-export declare function createNextJsCookieOAuthStateStore(): OAuthStateStore;

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

@@ -1,25 +0,0 @@
-import { OAuthStateStore } from './oauth-state-store';
-/**
- * Redis client interface (compatible with ioredis and node-redis)
- */
-export interface RedisClient {
-    set(key: string, value: string, mode?: string, duration?: number): Promise<string | null>;
-    get(key: string): Promise<string | null>;
-    del(key: string): Promise<number>;
-    keys(pattern: string): Promise<string[]>;
-}
-/**
- * Creates a Redis-based OAuth state store.
- *
- * @param redis - Redis client instance (ioredis or node-redis)
- * @param keyPrefix - Key prefix for state keys (default: 'mulguard:oauth:state:')
- * @returns OAuth state store implementation
- *
- * @example
- * ```typescript
- * import Redis from 'ioredis'
- * const redis = new Redis(process.env.REDIS_URL)
- * const stateStore = createRedisOAuthStateStore(redis)
- * ```
- */
-export declare function createRedisOAuthStateStore(redis: RedisClient, keyPrefix?: string): OAuthStateStore;

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

@@ -1,45 +0,0 @@
-/**
- * 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;
-export { createCookieOAuthStateStore, createNextJsCookieOAuthStateStore, type CookieHandler, type CookieOAuthStateStoreConfig, } from './oauth-state-store-cookie';

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

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

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

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

@@ -1,33 +0,0 @@
-import { MulguardInstance } from '../../mulguard';
-import { EmailCredentials, AuthResult } from '../types';
-/**
- * Unified sign in function - delegates to auth.signIn unified logic
- *
- * @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

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

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