mulguard 1.1.7 → 1.1.8

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

@@ -1,145 +0,0 @@
-import { EmailCredentials, AuthResult, User, Session } from '../types';
-import { SecurityManager } from '../security/security-manager';
-import { Logger } from '../logger';
-/**
- * Email/password authentication configuration.
- */
-export interface EmailPasswordConfig {
-    readonly security?: SecurityManager;
-    readonly logger?: Logger;
-    readonly requireEmailVerification?: boolean;
-    readonly maxLoginAttempts?: number;
-    readonly lockoutDuration?: number;
-}
-/**
- * Email/password authentication handler.
- *
- * Provides secure email/password authentication with validation,
- * rate limiting, and account lockout protection.
- *
- * @example
- * ```typescript
- * const handler = new EmailPasswordAuth({
- *   security: securityManager,
- *   logger: logger,
- * })
- *
- * const result = await handler.authenticate({
- *   email: 'user@example.com',
- *   password: 'password123',
- * }, async (email) => {
- *   // Your custom user lookup logic
- *   return await db.user.findUnique({ where: { email } })
- * })
- * ```
- */
-export declare class EmailPasswordAuth {
-    private readonly config;
-    private readonly security;
-    private readonly loginAttempts;
-    constructor(config?: EmailPasswordConfig);
-    /**
-     * Authenticates a user with email and password.
-     *
-     * @template TUser - User type
-     * @template TSession - Session type
-     * @param credentials - Email and password credentials
-     * @param userLookup - Function to lookup user by email
-     * @param passwordVerify - Function to verify password (optional, uses comparePassword if not provided)
-     * @param createSession - Function to create session (optional)
-     * @returns Authentication result
-     *
-     * @example
-     * ```typescript
-     * const result = await handler.authenticate(
-     *   { email: 'user@example.com', password: 'password123' },
-     *   async (email) => await db.user.findUnique({ where: { email } }),
-     *   async (password, hash) => await bcrypt.compare(password, hash)
-     * )
-     * ```
-     */
-    authenticate<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(credentials: EmailCredentials, userLookup: (email: string) => Promise<TUser | null>, passwordVerify?: (password: string, hash: string) => Promise<boolean>, createSession?: (user: TUser) => Promise<TSession>): Promise<AuthResult<TUser, TSession>>;
-    /**
-     * Checks if account is locked.
-     *
-     * @param email - User email
-     * @returns Lockout status
-     */
-    private checkAccountLockout;
-    /**
-     * Records a failed login attempt.
-     *
-     * @param email - User email
-     */
-    private recordFailedAttempt;
-    /**
-     * Clears failed login attempts for an email.
-     *
-     * @param email - User email
-     */
-    private clearFailedAttempts;
-    /**
-     * Resets login attempts for an email (for admin use).
-     *
-     * @param email - User email
-     */
-    resetLoginAttempts(email: string): void;
-}
-/**
- * Creates an email/password authentication handler.
- *
- * @param config - Email/password authentication configuration
- * @returns Email/password authentication handler
- *
- * @example
- * ```typescript
- * const handler = createEmailPasswordAuth({
- *   security: securityManager,
- *   logger: logger,
- * })
- * ```
- */
-export declare function createEmailPasswordAuth(config?: EmailPasswordConfig): EmailPasswordAuth;
-/**
- * TODO: Performance
- * - [ ] Add password hashing caching
- * - [ ] Optimize user lookup with caching
- * - [ ] Implement async password verification
- * - [ ] Add batch authentication support
- *
- * TODO: Features
- * - [ ] Add password reset functionality
- * - [ ] Implement password change with old password verification
- * - [ ] Add password history tracking
- * - [ ] Create password expiration support
- * - [ ] Add account recovery options
- * - [ ] Implement remember me functionality
- *
- * TODO: Security
- * - [ ] Add password breach checking (Have I Been Pwned)
- * - [ ] Implement password strength requirements
- * - [ ] Add two-factor authentication integration
- * - [ ] Create security event logging
- * - [ ] Add IP-based lockout
- *
- * TODO: Type Safety
- * - [ ] Add branded types for email addresses
- * - [ ] Create type-safe password handling
- * - [ ] Implement compile-time validation rules
- *
- * TODO: Testing
- * - [ ] Add comprehensive unit tests
- * - [ ] Test account lockout mechanism
- * - [ ] Test rate limiting integration
- * - [ ] Add password verification tests
- *
- * TODO: Documentation
- * - [ ] Document authentication flow
- * - [ ] Add password policy guide
- * - [ ] Create security best practices guide
- *
- * TODO: Limitations
- * - [ ] Password verification must be implemented by user
- * - [ ] Account lockout is in-memory (consider persistent storage)
- * - [ ] No password hashing included (use bcrypt, argon2, etc.)
- */

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

@@ -1,14 +0,0 @@
-/**
- * OAuth 2.0 Module for Mulguard Authentication Library.
- *
- * Provides comprehensive OAuth authentication with PKCE support,
- * state management, and provider integrations.
- *
- * @module @mulguard/core/auth/oauth
- */
-export * from './providers';
-export * from './pkce';
-export * from './state-store';
-export * from './state-store-cookie';
-export * from './state-store-redis';
-export * from './oauth-handler';

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

@@ -1,172 +0,0 @@
-import { OAuthProvidersConfig, OAuthUserInfo, AuthResult, User, Session } from '../../types';
-import { PKCEStorageAdapter } from './pkce';
-import { OAuthStateStore } from './state-store';
-import { Logger } from '../../logger';
-/**
- * OAuth handler configuration.
- */
-export interface OAuthHandlerConfig {
-    readonly providers: OAuthProvidersConfig;
-    readonly baseUrl: string;
-    readonly pkce?: {
-        readonly enabled: boolean;
-        readonly storage?: PKCEStorageAdapter;
-    };
-    readonly stateStore?: OAuthStateStore;
-    readonly logger?: Logger;
-}
-/**
- * OAuth initiation result with authorization URL and state.
- */
-export interface OAuthInitiationResult {
-    readonly url: string;
-    readonly state: string;
-    readonly codeVerifier?: string;
-}
-/**
- * Comprehensive OAuth 2.0 handler with PKCE support.
- *
- * Provides secure OAuth authentication flow with PKCE protection,
- * state management, and comprehensive error handling.
- *
- * @example
- * ```typescript
- * const handler = new OAuthHandler({
- *   providers: {
- *     google: { clientId: '...', clientSecret: '...' },
- *   },
- *   baseUrl: 'https://example.com',
- *   pkce: { enabled: true },
- * })
- *
- * // Initiate OAuth flow
- * const { url, state, codeVerifier } = await handler.initiate('google')
- *
- * // Handle callback
- * const result = await handler.handleCallback('google', code, state, codeVerifier)
- * ```
- */
-export declare class OAuthHandler {
-    private readonly config;
-    private readonly pkceStorage;
-    constructor(config: OAuthHandlerConfig);
-    /**
-     * Initiates OAuth authentication flow.
-     *
-     * Generates authorization URL with PKCE (if enabled) and CSRF state token.
-     *
-     * @param providerId - OAuth provider identifier
-     * @returns OAuth initiation result with authorization URL and state
-     *
-     * @example
-     * ```typescript
-     * const { url, state, codeVerifier } = await handler.initiate('google')
-     * // Store state and codeVerifier securely
-     * // Redirect user to url
-     * ```
-     */
-    initiate(providerId: string): Promise<OAuthInitiationResult>;
-    /**
-     * Handles OAuth callback and completes authentication.
-     *
-     * Validates state token, verifies PKCE (if enabled), exchanges code for tokens,
-     * retrieves user profile, and creates session.
-     *
-     * @template TUser - User type
-     * @template TSession - Session type
-     * @param providerId - OAuth provider identifier
-     * @param code - Authorization code from OAuth callback
-     * @param state - CSRF state token
-     * @param codeVerifier - PKCE code verifier (required if PKCE is enabled)
-     * @param userLookup - Function to lookup/create user from OAuth profile
-     * @param createSession - Function to create session (optional)
-     * @returns Authentication result
-     *
-     * @example
-     * ```typescript
-     * const result = await handler.handleCallback(
-     *   'google',
-     *   code,
-     *   state,
-     *   storedCodeVerifier,
-     *   async (userInfo) => {
-     *     // Lookup or create user
-     *     return await db.user.findOrCreate({ email: userInfo.email })
-     *   }
-     * )
-     * ```
-     */
-    handleCallback<TUser extends User = User, TSession extends Session<TUser> = Session<TUser>>(providerId: string, code: string, state: string, codeVerifier?: string, userLookup?: (userInfo: OAuthUserInfo) => Promise<TUser>, createSession?: (user: TUser, userInfo: OAuthUserInfo) => Promise<TSession>): Promise<AuthResult<TUser, TSession>>;
-    /**
-     * Validates OAuth state token.
-     *
-     * @param state - State token
-     * @param providerId - Provider identifier
-     * @returns True if state is valid
-     */
-    private validateState;
-}
-/**
- * Creates an OAuth handler instance.
- *
- * @param config - OAuth handler configuration
- * @returns OAuth handler instance
- *
- * @example
- * ```typescript
- * const handler = createOAuthHandler({
- *   providers: {
- *     google: { clientId: '...', clientSecret: '...' },
- *   },
- *   baseUrl: 'https://example.com',
- *   pkce: { enabled: true },
- * })
- * ```
- */
-export declare function createOAuthHandler(config: OAuthHandlerConfig): OAuthHandler;
-export * from './pkce';
-export * from './providers';
-/**
- * TODO: Performance
- * - [ ] Add OAuth token caching
- * - [ ] Optimize user profile retrieval
- * - [ ] Implement token refresh caching
- * - [ ] Add batch OAuth operations support
- *
- * TODO: Features
- * - [ ] Add OAuth token refresh support
- * - [ ] Implement OAuth token revocation
- * - [ ] Add OAuth provider discovery
- * - [ ] Create OAuth provider plugin system
- * - [ ] Add OAuth consent screen customization
- *
- * TODO: Security
- * - [ ] Add OAuth flow rate limiting
- * - [ ] Implement OAuth state encryption
- * - [ ] Add OAuth token validation
- * - [ ] Create security event logging
- * - [ ] Add OAuth flow monitoring
- *
- * TODO: Type Safety
- * - [ ] Add branded types for OAuth tokens
- * - [ ] Create type-safe provider configuration
- * - [ ] Implement compile-time validation
- *
- * TODO: Testing
- * - [ ] Add comprehensive unit tests
- * - [ ] Test PKCE flow end-to-end
- * - [ ] Test state validation
- * - [ ] Add provider-specific tests
- *
- * TODO: Documentation
- * - [ ] Document OAuth flow
- * - [ ] Add PKCE setup guide
- * - [ ] Create provider configuration guide
- * - [ ] Document security best practices
- *
- * TODO: Limitations
- * - [ ] PKCE storage is in-memory (consider Redis for production)
- * - [ ] State storage is in-memory (consider Redis for production)
- * - [ ] Token refresh not implemented yet
- * - [ ] No support for custom OAuth providers yet
- */

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

@@ -1,168 +0,0 @@
-/**
- * PKCE (Proof Key for Code Exchange) Implementation for OAuth 2.0.
- *
- * Provides secure PKCE code generation and verification for OAuth flows
- * to prevent authorization code interception attacks.
- *
- * @module @mulguard/core/auth/oauth/pkce
- *
- * @see {@link https://tools.ietf.org/html/rfc7636} RFC 7636 - PKCE
- */
-/**
- * PKCE code challenge method.
- */
-export type PKCECodeChallengeMethod = 'S256' | 'plain';
-/**
- * PKCE code pair (verifier and challenge).
- */
-export interface PKCECodePair {
-    readonly codeVerifier: string;
-    readonly codeChallenge: string;
-    readonly codeChallengeMethod: PKCECodeChallengeMethod;
-}
-/**
- * PKCE verification result.
- */
-export interface PKCEVerificationResult {
-    readonly valid: boolean;
-    readonly error?: string;
-}
-/**
- * Generates a cryptographically secure random string for PKCE code verifier.
- *
- * Uses URL-safe base64 encoding (base64url) as per RFC 7636.
- *
- * @param length - Code verifier length (43-128, default: 43)
- * @returns Base64url-encoded code verifier
- *
- * @example
- * ```typescript
- * const verifier = generateCodeVerifier()
- * // Returns: 'abc123xyz...' (43 characters, base64url encoded)
- * ```
- */
-export declare function generateCodeVerifier(length?: number): string;
-/**
- * Generates PKCE code challenge from verifier using S256 method.
- *
- * Uses SHA256 hash and base64url encoding as per RFC 7636.
- *
- * @param codeVerifier - Code verifier
- * @returns Base64url-encoded code challenge
- *
- * @example
- * ```typescript
- * const verifier = generateCodeVerifier()
- * const challenge = generateCodeChallenge(verifier)
- * // Returns: 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' (base64url encoded SHA256 hash)
- * ```
- */
-export declare function generateCodeChallenge(codeVerifier: string): string;
-/**
- * Generates a complete PKCE code pair (verifier + challenge).
- *
- * @param length - Code verifier length (default: 43)
- * @param method - Code challenge method (default: 'S256')
- * @returns PKCE code pair
- *
- * @example
- * ```typescript
- * const { codeVerifier, codeChallenge } = generatePKCECodePair()
- * // Store codeVerifier securely (e.g., in session)
- * // Use codeChallenge in authorization URL
- * ```
- */
-export declare function generatePKCECodePair(length?: number, method?: PKCECodeChallengeMethod): PKCECodePair;
-/**
- * Verifies PKCE code challenge against code verifier.
- *
- * Uses constant-time comparison to prevent timing attacks.
- *
- * @param codeVerifier - Code verifier (from stored session)
- * @param codeChallenge - Code challenge (from authorization request)
- * @param method - Code challenge method (default: 'S256')
- * @returns Verification result
- *
- * @example
- * ```typescript
- * const result = verifyPKCECode(storedVerifier, receivedChallenge)
- * if (!result.valid) {
- *   throw new Error(result.error)
- * }
- * ```
- */
-export declare function verifyPKCECode(codeVerifier: string, codeChallenge: string, method?: PKCECodeChallengeMethod): PKCEVerificationResult;
-/**
- * PKCE code storage adapter interface.
- */
-export interface PKCEStorageAdapter {
-    /**
-     * Stores PKCE code verifier.
-     *
-     * @param key - Storage key (e.g., state token)
-     * @param codeVerifier - Code verifier to store
-     * @param expiresIn - Expiration time in milliseconds
-     */
-    set(key: string, codeVerifier: string, expiresIn: number): Promise<void>;
-    /**
-     * Gets PKCE code verifier.
-     *
-     * @param key - Storage key
-     * @returns Code verifier or null if not found/expired
-     */
-    get(key: string): Promise<string | null>;
-    /**
-     * Deletes PKCE code verifier.
-     *
-     * @param key - Storage key
-     */
-    delete(key: string): Promise<void>;
-}
-/**
- * In-memory PKCE storage adapter.
- */
-export declare class MemoryPKCEStorage implements PKCEStorageAdapter {
-    private readonly storage;
-    set(key: string, codeVerifier: string, expiresIn: number): Promise<void>;
-    get(key: string): Promise<string | null>;
-    delete(key: string): Promise<void>;
-}
-/**
- * TODO: Performance
- * - [ ] Add PKCE code pair caching
- * - [ ] Optimize SHA256 hashing for high-frequency operations
- * - [ ] Consider Web Crypto API for browser environments
- *
- * TODO: Features
- * - [ ] Add Redis-based PKCE storage adapter
- * - [ ] Implement PKCE code rotation
- * - [ ] Add PKCE code expiration tracking
- * - [ ] Create PKCE code cleanup job
- *
- * TODO: Security
- * - [ ] Add PKCE code generation rate limiting
- * - [ ] Implement PKCE code audit logging
- * - [ ] Add PKCE code strength validation
- * - [ ] Create security event monitoring
- *
- * TODO: Type Safety
- * - [ ] Add branded types for code verifier/challenge
- * - [ ] Create type-safe PKCE storage
- * - [ ] Implement compile-time validation
- *
- * TODO: Testing
- * - [ ] Add comprehensive unit tests
- * - [ ] Test constant-time comparison
- * - [ ] Test code generation randomness
- * - [ ] Add storage adapter tests
- *
- * TODO: Documentation
- * - [ ] Document PKCE flow
- * - [ ] Add security considerations guide
- * - [ ] Create PKCE best practices guide
- *
- * TODO: Limitations
- * - [ ] PKCE storage is in-memory (consider Redis for production)
- * - [ ] Code generation uses Node.js Buffer (consider Web Crypto API for browsers)
- * - [ ] Plain method is supported but not recommended
- */

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

@@ -1,198 +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
- * @param codeVerifier - PKCE code verifier (optional)
- * @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',
- *   'code_verifier'
- * )
- * console.log(tokens.access_token)
- * ```
- */
-export declare function exchangeOAuthCode(providerId: string, config: OAuthProviderConfig, code: string, redirectUri: string, codeVerifier?: 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 getUserProfile('google', 'access_token_123')
- * console.log(profile.email, profile.name)
- * ```
- */
-export declare function getUserProfile(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 { getUserProfile as getOAuthUserInfo };
-/**
- * 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
- * - [ ] 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
- */