mulguard 1.1.6 → 1.1.7

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

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

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

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

@@ -0,0 +1,168 @@
+/**
+ * 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 → oauth/providers.d.ts}

@@ -1,4 +1,4 @@
-import { OAuthProviderConfig } from '../types';
+import { OAuthProviderConfig } from '../../types';
 /**
  * OAuth provider identifier.
  */
@@ -106,6 +106,7 @@ export declare function buildOAuthAuthorizationUrl(providerId: string, config: O
  * @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
  *
@@ -115,12 +116,13 @@ export declare function buildOAuthAuthorizationUrl(providerId: string, config: O
  *   'google',
  *   { clientId: '...', clientSecret: '...' },
  *   'code123',
- *   'https://example.com/callback'
+ *   'https://example.com/callback',
+ *   'code_verifier'
  * )
  * console.log(tokens.access_token)
  * ```
  */
-export declare function exchangeOAuthCode(providerId: string, config: OAuthProviderConfig, code: string, redirectUri: string): Promise<TokenExchangeResult>;
+export declare function exchangeOAuthCode(providerId: string, config: OAuthProviderConfig, code: string, redirectUri: string, codeVerifier?: string): Promise<TokenExchangeResult>;
 /**
  * Retrieves user information from OAuth provider.
  *
@@ -131,11 +133,11 @@ export declare function exchangeOAuthCode(providerId: string, config: OAuthProvi
  *
  * @example
  * ```typescript
- * const profile = await getOAuthUserInfo('google', 'access_token_123')
+ * const profile = await getUserProfile('google', 'access_token_123')
  * console.log(profile.email, profile.name)
  * ```
  */
-export declare function getOAuthUserInfo(providerId: string, accessToken: string): Promise<OAuthUserProfile>;
+export declare function getUserProfile(providerId: string, accessToken: string): Promise<OAuthUserProfile>;
 /**
  * Type predicate to check if a value is a valid OAuth provider config.
  *
@@ -143,7 +145,7 @@ export declare function getOAuthUserInfo(providerId: string, accessToken: string
  * @returns True if value is a valid OAuth provider config
  */
 export declare function isOAuthProviderConfig(value: unknown): value is OAuthProviderConfig;
-export {};
+export { getUserProfile as getOAuthUserInfo };
 /**
  * TODO: Performance
  * - [ ] Add token exchange result caching (with TTL)
@@ -152,7 +154,6 @@ export {};
  * - [ ] 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

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

@@ -1,8 +1,8 @@
-import { OAuthStateStore } from './oauth-state-store';
+import { OAuthStateStore } from './state-store';
 /**
  * Cookie options interface
  */
-export interface CookieOptions {
+export interface OAuthCookieOptions {
     httpOnly?: boolean;
     secure?: boolean;
     sameSite?: 'strict' | 'lax' | 'none';
@@ -21,7 +21,7 @@ export interface CookieHandler {
     /**
      * Set cookie with options
      */
-    setCookie(name: string, value: string, options: CookieOptions): Promise<void> | void;
+    setCookie(name: string, value: string, options: OAuthCookieOptions): Promise<void> | void;
     /**
      * Delete cookie
      */
@@ -72,7 +72,7 @@ export declare function createCookieOAuthStateStore(config: CookieOAuthStateStor
  *
  * @example
  * ```typescript
- * import { createNextJsCookieOAuthStateStore } from 'mulguard/core/auth/oauth-state-store-cookie'
+ * import { createNextJsCookieOAuthStateStore } from 'mulguard/core/auth/oauth/state-store-cookie'
  *
  * export const auth = mulguard({
  *   oauthStateStore: createNextJsCookieOAuthStateStore(),

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

@@ -1,4 +1,4 @@
-import { OAuthStateStore } from './oauth-state-store';
+import { OAuthStateStore } from './state-store';
 /**
  * Redis client interface (compatible with ioredis and node-redis)
  */

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

@@ -4,6 +4,8 @@
  *
  * Default implementation uses in-memory Map (for development)
  * Production should use Redis, database, or other persistent store
+ *
+ * @module @mulguard/core/auth/oauth/state-store
  */
 export interface OAuthState {
     provider: string;
@@ -42,4 +44,5 @@ export declare class MemoryOAuthStateStore implements OAuthStateStore {
  * Create default in-memory OAuth state store
  */
 export declare function createMemoryOAuthStateStore(): OAuthStateStore;
-export { createCookieOAuthStateStore, createNextJsCookieOAuthStateStore, type CookieHandler, type CookieOAuthStateStoreConfig, } from './oauth-state-store-cookie';
+export { createCookieOAuthStateStore, createNextJsCookieOAuthStateStore, type CookieHandler, type CookieOAuthStateStoreConfig, } from './state-store-cookie';
+export { createRedisOAuthStateStore, type RedisClient, } from './state-store-redis';