@bernierllc/auth-suite 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bernier LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,468 @@
+# @bernierllc/auth-suite
+
+Complete authentication suite with multi-provider support, session management, role-based access control, and multi-factor authentication.
+
+## Features
+
+- **🔐 Complete Authentication** - Built on @bernierllc/auth-service
+- **💫 Enhanced Session Management** - Memory, Redis, or database storage with auto-cleanup
+- **🛡️ Role-Based Access Control (RBAC)** - Hierarchical roles and permissions
+- **📱 Multi-Factor Authentication** - TOTP, SMS, email, and backup codes
+- **📊 Comprehensive Audit Logging** - Track all authentication events
+- **🔌 OAuth/SAML/LDAP Integration** - Multiple provider support
+- **🚀 Advanced Security Features** - Session management, permission checks
+- **📈 Production Ready** - Built with crypto-utils for enterprise security
+
+## Installation
+
+```bash
+npm install @bernierllc/auth-suite
+```
+
+## Quick Start
+
+```typescript
+import { AuthSuite } from '@bernierllc/auth-suite';
+
+// Initialize with enhanced features
+const authSuite = new AuthSuite({
+  // Core auth configuration
+  jwt: {
+    secret: process.env.JWT_SECRET,
+    expiresIn: '15m',
+    refreshExpiresIn: '7d'
+  },
+  
+  // Enhanced session management
+  sessions: {
+    enabled: true,
+    storage: 'memory', // or 'redis', 'database'
+    cleanup: {
+      enabled: true,
+      intervalMs: 60000, // 1 minute
+      maxIdleMs: 24 * 60 * 60 * 1000 // 24 hours
+    }
+  },
+
+  // Role-based access control
+  rbac: {
+    enabled: true,
+    hierarchical: true,
+    roles: [
+      {
+        name: 'admin',
+        description: 'System administrator',
+        permissions: ['*:*'] // All permissions
+      },
+      {
+        name: 'user',
+        description: 'Regular user',
+        permissions: ['profile:read', 'profile:update']
+      }
+    ],
+    permissions: [
+      {
+        name: 'profile:read',
+        description: 'Read user profile',
+        resource: 'profile',
+        actions: ['read']
+      }
+    ]
+  },
+
+  // Multi-factor authentication
+  mfaEnhanced: {
+    enabled: true,
+    providers: [
+      {
+        type: 'totp',
+        name: 'Google Authenticator',
+        enabled: true,
+        config: {}
+      }
+    ],
+    requirements: [
+      {
+        trigger: 'login',
+        providers: ['totp'],
+        conditions: {}
+      }
+    ]
+  },
+
+  // Audit logging
+  auditing: {
+    enabled: true,
+    events: ['login', 'logout', 'register', 'permission_change'],
+    storage: 'file',
+    retention: {
+      days: 90,
+      maxSize: '100MB'
+    }
+  }
+});
+
+// Register user with enhanced features
+const registerResult = await authSuite.register({
+  username: 'johndoe',
+  email: 'john@example.com',
+  password: 'SecurePass123!',
+  firstName: 'John',
+  lastName: 'Doe',
+  acceptTerms: true
+});
+
+if (registerResult.success) {
+  console.log('User registered with session:', registerResult.session);
+  console.log('Assigned permissions:', registerResult.permissions);
+}
+
+// Login with potential MFA
+const loginResult = await authSuite.login({
+  email: 'john@example.com',
+  password: 'SecurePass123!'
+});
+
+if (loginResult.mfaRequired) {
+  console.log('MFA required, challenge:', loginResult.mfaChallenge);
+  
+  // Complete MFA verification
+  const mfaResult = await authSuite.completeMfaLogin(
+    loginResult.mfaChallenge.challengeId,
+    '123456' // TOTP code from authenticator app
+  );
+  
+  if (mfaResult.success) {
+    console.log('Login complete with MFA');
+  }
+}
+```
+
+## Core Features
+
+### Enhanced Session Management
+
+```typescript
+// Session automatically created on login/register
+const result = await authSuite.login(credentials);
+if (result.success && result.session) {
+  console.log('Session ID:', result.session.sessionId);
+  console.log('Expires at:', result.session.expiresAt);
+}
+
+// Manual session management
+const session = await authSuite.sessionManager.create('user-id', {
+  customData: 'value'
+});
+
+// Cleanup expired sessions
+const cleaned = await authSuite.cleanup();
+console.log(`Cleaned up ${cleaned.sessions} expired sessions`);
+```
+
+### Role-Based Access Control (RBAC)
+
+```typescript
+// Check permissions
+const permissionResult = await authSuite.checkPermission({
+  userId: 'user-123',
+  resource: 'documents',
+  action: 'delete',
+  context: { ownerId: 'user-123' }
+});
+
+if (permissionResult.allowed) {
+  console.log('User can delete documents');
+} else {
+  console.log('Access denied:', permissionResult.reason);
+}
+
+// Assign roles
+await authSuite.rbacManager.assignRole('user-123', 'admin');
+
+// Get user permissions
+const permissions = await authSuite.getUserPermissions('user-123');
+console.log('User permissions:', permissions);
+```
+
+### Multi-Factor Authentication
+
+```typescript
+// Setup MFA for user
+const mfaSetup = await authSuite.setupMfa('user-123', 'totp');
+console.log('Show QR code to user:', mfaSetup.qrCode);
+
+// Verify setup
+const setupVerified = await authSuite.mfaManager.verifySetup('user-123', '123456');
+
+// Generate backup codes
+const backupCodes = await authSuite.mfaManager.regenerateBackupCodes('user-123');
+console.log('Backup codes:', backupCodes);
+
+// Verify backup code
+const backupValid = await authSuite.mfaManager.verifyBackupCode('user-123', 'backup-code');
+```
+
+### Audit Logging
+
+```typescript
+// Logs are automatically generated for auth events
+// Query audit logs
+const auditLogs = await authSuite.getAuditLogs({
+  userId: 'user-123',
+  event: 'login',
+  startDate: new Date('2025-01-01'),
+  limit: 50
+});
+
+// Get audit statistics
+const stats = await authSuite.auditManager.getLogStats();
+console.log('Audit stats:', stats);
+
+// Search logs
+const searchResults = await authSuite.auditManager.searchLogs('failed login');
+```
+
+## Configuration
+
+### Complete Configuration Options
+
+```typescript
+interface AuthSuiteConfig {
+  // Core auth service configuration
+  jwt: {
+    secret: string;
+    issuer?: string;
+    audience?: string;
+    expiresIn?: string | number;
+    refreshExpiresIn?: string | number;
+    algorithm?: JWTAlgorithm;
+  };
+
+  // Password policy
+  password: {
+    minLength: number;
+    requireUppercase: boolean;
+    requireLowercase: boolean;
+    requireNumbers: boolean;
+    requireSymbols: boolean;
+    preventReuse?: number;
+    maxAge?: number;
+  };
+
+  // Enhanced session management
+  sessions?: {
+    enabled?: boolean; // default: true
+    storage?: 'memory' | 'redis' | 'database'; // default: 'memory'
+    cleanup?: {
+      enabled: boolean; // default: true
+      intervalMs: number; // default: 60000 (1 minute)
+      maxIdleMs: number; // default: 24 hours
+    };
+    persistence?: {
+      enabled: boolean; // default: false
+      ttl: number; // default: 7 days
+    };
+  };
+
+  // Role-based access control
+  rbac?: {
+    enabled: boolean; // default: false
+    hierarchical: boolean; // default: false
+    roles: RoleDefinition[];
+    permissions: PermissionDefinition[];
+  };
+
+  // Multi-factor authentication
+  mfaEnhanced?: {
+    enabled: boolean; // default: false
+    providers: MfaProvider[];
+    requirements: MfaRequirement[];
+    backup: {
+      enabled: boolean; // default: true
+      codeCount: number; // default: 10
+      codeLength: number; // default: 8
+    };
+  };
+
+  // Audit logging
+  auditing?: {
+    enabled: boolean; // default: true
+    events: AuditEvent[];
+    storage: 'file' | 'database' | 'external'; // default: 'file'
+    retention: {
+      days: number; // default: 90
+      maxSize: string; // default: '100MB'
+    };
+  };
+
+  // Security settings
+  security: {
+    maxLoginAttempts: number;
+    lockoutDuration: number;
+    sessionTimeout: number;
+    requireEmailVerification: boolean;
+    allowMultipleSessions: boolean;
+  };
+}
+```
+
+### Role Definition
+
+```typescript
+interface RoleDefinition {
+  name: string;
+  description: string;
+  permissions: string[]; // e.g., ['users:read', 'documents:*']
+  parent?: string; // for hierarchical roles
+  metadata?: Record<string, any>;
+}
+```
+
+### Permission Definition
+
+```typescript
+interface PermissionDefinition {
+  name: string; // e.g., 'documents:delete'
+  description: string;
+  resource: string; // e.g., 'documents'
+  actions: string[]; // e.g., ['delete']
+  conditions?: PermissionCondition[]; // conditional permissions
+}
+```
+
+## API Reference
+
+### Class: AuthSuite
+
+#### Core Authentication
+
+- `register(credentials: RegisterCredentials): Promise<AuthSuiteResult>`
+- `login(credentials: LoginCredentials): Promise<AuthSuiteResult>`
+- `verifyToken(token: string): Promise<User | null>`
+- `logout(sessionId?: string): Promise<{success: boolean}>`
+
+#### MFA Management
+
+- `setupMfa(userId: string, type: string): Promise<{secret: string; qrCode?: string}>`
+- `completeMfaLogin(challengeId: string, response: string): Promise<AuthSuiteResult>`
+
+#### Permission Management
+
+- `checkPermission(check: PermissionCheck): Promise<PermissionResult>`
+- `getUserRoles(userId: string): Promise<string[]>`
+- `getUserPermissions(userId: string): Promise<string[]>`
+
+#### Audit and Cleanup
+
+- `getAuditLogs(filters: AuditQueryFilters): Promise<AuditLog[]>`
+- `cleanup(): Promise<{sessions: number; auditLogs: number}>`
+
+### Manager Classes
+
+For advanced usage, managers can be used directly:
+
+```typescript
+import { 
+  MemorySessionManager, 
+  BasicRBACManager, 
+  TOTPMfaManager, 
+  FileAuditManager 
+} from '@bernierllc/auth-suite';
+```
+
+## Integration with Crypto-Utils
+
+This suite leverages `@bernierllc/crypto-utils` for:
+
+- **JWT Generation & Verification** - Secure token handling
+- **Magic Links** - Password reset functionality  
+- **API Key Generation** - MFA backup codes and secrets
+- **Password Hashing** - Secure password storage
+
+## Dependencies
+
+- `@bernierllc/auth-service` - Core authentication service
+- `@bernierllc/crypto-utils` - Cryptographic utilities
+- `@bernierllc/logger` - Structured logging
+- `bcrypt` - Password hashing
+- `uuid` - Unique ID generation
+
+## Production Considerations
+
+### Session Storage
+
+For production deployments:
+
+- **Memory**: Fast but not persistent, use for single-instance apps
+- **Redis**: Recommended for multi-instance deployments
+- **Database**: Use for full persistence and audit requirements
+
+### Security
+
+- Use strong JWT secrets (256-bit minimum)
+- Enable MFA for sensitive applications
+- Configure appropriate session timeouts
+- Monitor audit logs for suspicious activity
+- Use HTTPS in production
+- Implement rate limiting
+
+### Performance
+
+- Cleanup expired sessions regularly
+- Index audit log queries for performance
+- Consider external audit log storage for high-volume applications
+- Use Redis for session storage in clustered environments
+
+## Examples
+
+### Basic Usage
+
+```typescript
+const authSuite = new AuthSuite({
+  jwt: { secret: process.env.JWT_SECRET },
+  sessions: { enabled: true },
+  auditing: { enabled: true }
+});
+```
+
+### Enterprise Setup
+
+```typescript
+const authSuite = new AuthSuite({
+  jwt: {
+    secret: process.env.JWT_SECRET,
+    expiresIn: '15m',
+    refreshExpiresIn: '7d',
+    issuer: 'mycompany.com'
+  },
+  rbac: {
+    enabled: true,
+    hierarchical: true,
+    roles: enterpriseRoles,
+    permissions: enterprisePermissions
+  },
+  mfaEnhanced: {
+    enabled: true,
+    providers: [
+      { type: 'totp', name: 'Authenticator', enabled: true, config: {} }
+    ],
+    requirements: [
+      { trigger: 'login', providers: ['totp'] }
+    ]
+  },
+  sessions: {
+    storage: 'redis',
+    cleanup: { enabled: true, intervalMs: 30000 }
+  },
+  auditing: {
+    enabled: true,
+    storage: 'database',
+    retention: { days: 365, maxSize: '1GB' }
+  }
+});
+```
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { AuthSuite } from './suite';
+export type * from './types';
+export type { EmailVerificationResult } from './types';
+export { MemorySessionManager } from './managers/session-manager';
+export { BasicRBACManager } from './managers/rbac-manager';
+export { TOTPMfaManager } from './managers/mfa-manager';
+export { FileAuditManager } from './managers/audit-manager';
+export * from '@bernierllc/auth-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,mBAAmB,SAAS,CAAC;AAC7B,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileAuditManager = exports.TOTPMfaManager = exports.BasicRBACManager = exports.MemorySessionManager = exports.AuthSuite = void 0;
+// Main exports
+var suite_1 = require("./suite");
+Object.defineProperty(exports, "AuthSuite", { enumerable: true, get: function () { return suite_1.AuthSuite; } });
+// Manager exports for advanced usage
+var session_manager_1 = require("./managers/session-manager");
+Object.defineProperty(exports, "MemorySessionManager", { enumerable: true, get: function () { return session_manager_1.MemorySessionManager; } });
+var rbac_manager_1 = require("./managers/rbac-manager");
+Object.defineProperty(exports, "BasicRBACManager", { enumerable: true, get: function () { return rbac_manager_1.BasicRBACManager; } });
+var mfa_manager_1 = require("./managers/mfa-manager");
+Object.defineProperty(exports, "TOTPMfaManager", { enumerable: true, get: function () { return mfa_manager_1.TOTPMfaManager; } });
+var audit_manager_1 = require("./managers/audit-manager");
+Object.defineProperty(exports, "FileAuditManager", { enumerable: true, get: function () { return audit_manager_1.FileAuditManager; } });
+// Re-export auth-service for convenience
+__exportStar(require("@bernierllc/auth-service"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;;;;;;;;;;;;;;;AAEF,eAAe;AACf,iCAAoC;AAA3B,kGAAA,SAAS,OAAA;AAMlB,qCAAqC;AACrC,8DAAkE;AAAzD,uHAAA,oBAAoB,OAAA;AAC7B,wDAA2D;AAAlD,gHAAA,gBAAgB,OAAA;AACzB,sDAAwD;AAA/C,6GAAA,cAAc,OAAA;AACvB,0DAA4D;AAAnD,iHAAA,gBAAgB,OAAA;AAEzB,yCAAyC;AACzC,2DAAyC"}

package/dist/managers/audit-manager.d.ts

@@ -0,0 +1,26 @@
+import type { AuditManager, AuditLog, AuditQueryFilters } from '../types';
+/**
+ * File-based audit manager
+ * For production use, consider database storage or external logging service
+ */
+export declare class FileAuditManager implements AuditManager {
+    private logs;
+    private config;
+    private maxLogs;
+    constructor(config: any);
+    log(event: Omit<AuditLog, 'id' | 'timestamp'>): Promise<void>;
+    query(filters: AuditQueryFilters): Promise<AuditLog[]>;
+    cleanup(olderThanDays: number): Promise<number>;
+    getLogStats(): Promise<{
+        total: number;
+        byLevel: Record<string, number>;
+        byEvent: Record<string, number>;
+        oldestLog?: Date;
+        newestLog?: Date;
+    }>;
+    exportLogs(format?: 'json' | 'csv'): Promise<string>;
+    searchLogs(searchTerm: string): Promise<AuditLog[]>;
+    private parseMaxSize;
+    private exportToCsv;
+}
+//# sourceMappingURL=audit-manager.d.ts.map

package/dist/managers/audit-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-manager.d.ts","sourceRoot":"","sources":["../../src/managers/audit-manager.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE1E;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,GAAG;IAKjB,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB7D,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAsCtD,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY/C,WAAW,IAAI,OAAO,CAAC;QAC3B,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,IAAI,CAAC;QACjB,SAAS,CAAC,EAAE,IAAI,CAAC;KAClB,CAAC;IA8BI,UAAU,CAAC,MAAM,GAAE,MAAM,GAAG,KAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ5D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAyBzD,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,WAAW;CAuBpB"}