mulguard 1.1.2 → 1.1.3

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

@@ -1,71 +1,197 @@
+import { OAuthProviderConfig } from '../types';
 /**
- * Built-in OAuth Provider Configurations
- * Simple auth.js-like configuration for OAuth providers
+ * OAuth provider identifier.
  */
+export type OAuthProviderId = 'google' | 'github' | 'apple' | 'facebook' | string;
 /**
- * OAuth Provider Configuration (auth.js-like)
+ * Provider metadata for OAuth endpoints and configuration.
  */
-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>;
+export interface ProviderMetadata {
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    readonly userInfoUrl: string;
+    readonly defaultScopes: readonly string[];
+    readonly defaultParams?: Readonly<Record<string, string>>;
 }
 /**
- * OAuth Providers Configuration
- * Simple auth.js-like interface
+ * Normalized OAuth user profile.
  */
-export interface OAuthProvidersConfig {
-    google?: OAuthProviderConfig;
-    github?: OAuthProviderConfig;
-    apple?: OAuthProviderConfig;
-    facebook?: OAuthProviderConfig;
-    [key: string]: OAuthProviderConfig | undefined;
+export interface OAuthUserProfile {
+    readonly id: string;
+    readonly email: string;
+    readonly name: string;
+    readonly avatar?: string;
+    readonly emailVerified?: boolean;
+    readonly rawProfile: Readonly<Record<string, unknown>>;
 }
 /**
- * Provider metadata for built-in providers
+ * OAuth token exchange result.
  */
-interface ProviderMetadata {
-    authorizationUrl: string;
-    tokenUrl: string;
-    userInfoUrl: string;
-    defaultScopes: string[];
-    defaultParams?: Record<string, string>;
+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;
 }
 /**
- * Get provider metadata
+ * 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;
 /**
- * Build OAuth authorization URL
+ * 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;
 /**
- * Exchange authorization code for tokens
+ * 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 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;
-}>;
+export declare function getOAuthUserInfo(providerId: string, accessToken: string): Promise<OAuthUserProfile>;
 /**
- * Get user info from OAuth provider
- * Returns normalized user info with raw profile data
+ * 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 getOAuthUserInfo(providerId: string, accessToken: string): Promise<{
-    id: string;
-    email: string;
-    name: string;
-    avatar?: string;
-    emailVerified?: boolean;
-    rawProfile: Record<string, unknown>;
-}>;
+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/mulguard/auth-handlers.d.ts

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

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

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

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

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