@vorionsys/security 1.0.0

package/dist/auth/mfa/totp.js

@@ -0,0 +1,324 @@
+/**
+ * TOTP (Time-based One-Time Password) MFA Implementation for Vorion Platform
+ *
+ * Provides secure two-factor authentication using TOTP standard (RFC 6238).
+ * Compatible with Google Authenticator, Authy, Microsoft Authenticator, and other TOTP apps.
+ *
+ * @module auth/mfa/totp
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { authenticator } from 'otplib';
+import { toDataURL } from 'qrcode';
+import { createLogger } from '../../common/logger.js';
+const logger = createLogger({ component: 'totp-service' });
+/**
+ * Default TOTP configuration optimized for security while maintaining broad compatibility.
+ * SHA256 is recommended by NIST and supported by most modern authenticator apps.
+ * Falls back to SHA1 only if explicitly configured for legacy compatibility.
+ */
+const DEFAULT_CONFIG = {
+    issuer: 'Vorion',
+    algorithm: 'SHA256',
+    digits: 6,
+    period: 30,
+    window: 1,
+};
+/**
+ * Service for managing TOTP-based multi-factor authentication.
+ *
+ * Provides methods for generating secrets, verifying tokens, managing backup codes,
+ * and generating QR codes for authenticator app enrollment.
+ *
+ * @example
+ * ```typescript
+ * const totpService = getTOTPService();
+ *
+ * // Generate a new secret for user enrollment
+ * const secret = totpService.generateTOTPSecret('user123', 'user@example.com');
+ *
+ * // Generate QR code for authenticator app scanning
+ * const qrCodeDataUrl = await totpService.generateQRCode(secret.otpauthUrl);
+ *
+ * // Verify a token from the user's authenticator app
+ * const isValid = await totpService.verifyToken(secret.secret, '123456');
+ * ```
+ */
+export class TOTPService {
+    config;
+    /**
+     * Creates a new TOTPService instance.
+     *
+     * @param config - Partial configuration to override defaults
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        logger.info('TOTPService initialized', { issuer: this.config.issuer });
+    }
+    /**
+     * Generates a new TOTP secret for user enrollment.
+     *
+     * Creates a cryptographically secure random secret and formats it as a
+     * base32 string along with an otpauth:// URL for QR code generation.
+     *
+     * @param userId - Unique identifier for the user
+     * @param email - User's email address (used as account name in authenticator apps)
+     * @returns TOTPSecret containing the secret and otpauth URL
+     *
+     * @example
+     * ```typescript
+     * const secret = totpService.generateTOTPSecret('user123', 'user@example.com');
+     * // secret.secret: 'JBSWY3DPEHPK3PXP...'
+     * // secret.otpauthUrl: 'otpauth://totp/Vorion:user@example.com?secret=...'
+     * ```
+     */
+    generateTOTPSecret(userId, email) {
+        // Generate a cryptographically secure random secret
+        const secret = authenticator.generateSecret();
+        // Build the otpauth URL for QR code generation
+        // keyuri(accountName, issuer, secret) - returns otpauth:// URL
+        const otpauthUrl = authenticator.keyuri(email, this.config.issuer, secret);
+        logger.debug('Generated TOTP secret', { userId, email });
+        return {
+            secret,
+            otpauthUrl,
+        };
+    }
+    /**
+     * Generates a QR code image as a data URL for authenticator app enrollment.
+     *
+     * The returned data URL can be directly used as an image src attribute
+     * or embedded in HTML/email for user scanning.
+     *
+     * @param otpauthUrl - The otpauth:// URL to encode in the QR code
+     * @returns Promise resolving to a data URL (base64 PNG image)
+     *
+     * @example
+     * ```typescript
+     * const dataUrl = await totpService.generateQRCode(secret.otpauthUrl);
+     * // Returns: 'data:image/png;base64,iVBORw0KGgo...'
+     * ```
+     */
+    async generateQRCode(otpauthUrl) {
+        try {
+            const dataUrl = await toDataURL(otpauthUrl, {
+                errorCorrectionLevel: 'M',
+                type: 'image/png',
+                margin: 2,
+                width: 256,
+            });
+            logger.debug('Generated QR code for TOTP enrollment');
+            return dataUrl;
+        }
+        catch (error) {
+            logger.error('Failed to generate QR code', { error });
+            throw new Error('Failed to generate QR code for TOTP enrollment');
+        }
+    }
+    /**
+     * Verifies a TOTP token against the stored secret.
+     *
+     * Accounts for clock drift by allowing tokens within the configured
+     * time window (default: 1 period before/after current time).
+     *
+     * @param secret - The base32 encoded secret associated with the user
+     * @param token - The 6 or 8 digit token from the authenticator app
+     * @returns Promise resolving to true if the token is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const isValid = await totpService.verifyToken(userSecret, '123456');
+     * if (isValid) {
+     *   // Grant access
+     * }
+     * ```
+     */
+    async verifyToken(secret, token) {
+        try {
+            // Ensure token is the expected length
+            if (token.length !== this.config.digits) {
+                logger.debug('Token verification failed: invalid length', {
+                    expected: this.config.digits,
+                    received: token.length,
+                });
+                return false;
+            }
+            // Ensure token contains only digits
+            if (!/^\d+$/.test(token)) {
+                logger.debug('Token verification failed: non-numeric characters');
+                return false;
+            }
+            // Configure authenticator options before verification
+            authenticator.options = {
+                digits: this.config.digits,
+                step: this.config.period,
+                window: this.config.window,
+            };
+            // check() returns boolean directly in otplib v12
+            const isValid = authenticator.check(token, secret);
+            logger.debug('Token verification completed', { valid: isValid });
+            return isValid;
+        }
+        catch (error) {
+            logger.error('Token verification error', { error });
+            return false;
+        }
+    }
+    /**
+     * Generates cryptographically secure backup codes for account recovery.
+     *
+     * Backup codes are formatted as readable groups (e.g., 'XXXX-XXXX')
+     * and should be hashed before storage using hashBackupCode().
+     *
+     * @param count - Number of backup codes to generate (default: 10)
+     * @returns Array of plain-text backup codes to show to the user once
+     *
+     * @example
+     * ```typescript
+     * const codes = totpService.generateBackupCodes(10);
+     * // Returns: ['A1B2-C3D4', 'E5F6-G7H8', ...]
+     *
+     * // Hash codes before storing
+     * const hashedCodes = codes.map(code => totpService.hashBackupCode(code));
+     * ```
+     */
+    generateBackupCodes(count = 10) {
+        const codes = [];
+        const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+        for (let i = 0; i < count; i++) {
+            // Generate 8 random bytes for each code
+            const bytes = randomBytes(8);
+            let code = '';
+            // Convert bytes to alphanumeric characters
+            for (let j = 0; j < 8; j++) {
+                code += characters[bytes[j] % characters.length];
+            }
+            // Format as XXXX-XXXX for readability
+            codes.push(`${code.slice(0, 4)}-${code.slice(4, 8)}`);
+        }
+        logger.debug('Generated backup codes', { count });
+        return codes;
+    }
+    /**
+     * Hashes a backup code for secure storage.
+     *
+     * Uses SHA-256 to create a one-way hash of the backup code.
+     * The plain-text code should never be stored.
+     *
+     * @param code - The plain-text backup code to hash
+     * @returns SHA-256 hash of the backup code (hex encoded)
+     *
+     * @example
+     * ```typescript
+     * const hashed = totpService.hashBackupCode('A1B2-C3D4');
+     * // Store 'hashed' in database, never store plain-text code
+     * ```
+     */
+    hashBackupCode(code) {
+        // Normalize the code (uppercase, remove formatting)
+        const normalizedCode = code.toUpperCase().replace(/[^A-Z0-9]/g, '');
+        return createHash('sha256').update(normalizedCode).digest('hex');
+    }
+    /**
+     * Verifies a backup code against a list of hashed codes.
+     *
+     * If valid, returns the index of the used code so it can be removed
+     * from the stored list (backup codes are single-use).
+     *
+     * @param code - The plain-text backup code entered by the user
+     * @param hashedCodes - Array of SHA-256 hashed backup codes from storage
+     * @returns Object indicating validity and the index of the matched code
+     *
+     * @example
+     * ```typescript
+     * const result = totpService.verifyBackupCode('A1B2-C3D4', storedHashedCodes);
+     * if (result.valid) {
+     *   // Remove used code from storage
+     *   storedHashedCodes.splice(result.usedIndex!, 1);
+     *   // Grant access
+     * }
+     * ```
+     */
+    verifyBackupCode(code, hashedCodes) {
+        const hashedInput = this.hashBackupCode(code);
+        // Use timing-safe comparison to prevent timing attacks
+        for (let i = 0; i < hashedCodes.length; i++) {
+            const storedHash = hashedCodes[i];
+            // Compare hashes using constant-time comparison
+            if (this.timingSafeEqual(hashedInput, storedHash)) {
+                logger.debug('Backup code verified successfully', { codeIndex: i });
+                return { valid: true, usedIndex: i };
+            }
+        }
+        logger.debug('Backup code verification failed: no match');
+        return { valid: false };
+    }
+    /**
+     * Performs a timing-safe string comparison to prevent timing attacks.
+     *
+     * @param a - First string to compare
+     * @param b - Second string to compare
+     * @returns true if strings are equal, false otherwise
+     */
+    timingSafeEqual(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        const bufferA = Buffer.from(a, 'utf8');
+        const bufferB = Buffer.from(b, 'utf8');
+        try {
+            const crypto = require('node:crypto');
+            return crypto.timingSafeEqual(bufferA, bufferB);
+        }
+        catch {
+            // Fallback for environments without timingSafeEqual
+            let result = 0;
+            for (let i = 0; i < bufferA.length; i++) {
+                result |= bufferA[i] ^ bufferB[i];
+            }
+            return result === 0;
+        }
+    }
+    /**
+     * Gets the current configuration.
+     *
+     * @returns The active TOTP configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+// Singleton instance
+let totpServiceInstance = null;
+/**
+ * Gets the singleton TOTPService instance.
+ *
+ * Creates a new instance on first call with default configuration.
+ * Subsequent calls return the same instance.
+ *
+ * @param config - Optional configuration for the service (only used on first call)
+ * @returns The TOTPService singleton instance
+ *
+ * @example
+ * ```typescript
+ * // Get default instance
+ * const totpService = getTOTPService();
+ *
+ * // Or initialize with custom config on first call
+ * const totpService = getTOTPService({ issuer: 'MyApp', digits: 8 });
+ * ```
+ */
+export function getTOTPService(config) {
+    if (!totpServiceInstance) {
+        totpServiceInstance = new TOTPService(config);
+    }
+    return totpServiceInstance;
+}
+/**
+ * Resets the singleton instance (primarily for testing).
+ *
+ * @internal
+ */
+export function resetTOTPService() {
+    totpServiceInstance = null;
+}
+//# sourceMappingURL=totp.js.map

package/dist/auth/mfa/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","sourceRoot":"","sources":["../../../src/auth/mfa/totp.ts"],"names":[],"mappings":"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"}

package/dist/auth/mfa/webauthn.d.ts

@@ -0,0 +1,224 @@
+/**
+ * WebAuthn/FIDO2 MFA Implementation for Vorion Platform
+ *
+ * Provides secure passwordless authentication using WebAuthn standard.
+ * Supports multiple authenticators per user including YubiKey, Touch ID,
+ * Windows Hello, and other FIDO2-compliant devices.
+ *
+ * @module auth/mfa/webauthn
+ */
+import type { PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, AuthenticationResponseJSON, AuthenticatorTransportFuture } from '@simplewebauthn/types';
+/**
+ * Authenticator transport types supported by WebAuthn
+ */
+export type AuthenticatorTransport = AuthenticatorTransportFuture;
+/**
+ * Configuration options for WebAuthn service
+ */
+export interface WebAuthnConfig {
+    /** Relying Party name displayed to users during registration */
+    rpName: string;
+    /** Relying Party ID (domain), e.g., 'vorion.ai' */
+    rpId: string;
+    /** Full origin URL, e.g., 'https://vorion.ai' */
+    origin: string;
+    /** Attestation conveyance preference */
+    attestation: 'none' | 'direct';
+    /** User verification requirement */
+    userVerification: 'required' | 'preferred' | 'discouraged';
+    /** Timeout for WebAuthn operations in milliseconds */
+    timeout: number;
+}
+/**
+ * Represents a stored WebAuthn credential
+ */
+export interface WebAuthnCredential {
+    /** Internal unique identifier */
+    id: string;
+    /** Base64URL encoded credential ID from authenticator */
+    credentialId: string;
+    /** Base64URL encoded public key */
+    publicKey: string;
+    /** Signature counter for replay attack prevention */
+    counter: number;
+    /** Type of device (e.g., 'singleDevice', 'multiDevice') */
+    deviceType: string;
+    /** Whether credential is backed up (e.g., iCloud Keychain) */
+    backedUp: boolean;
+    /** Supported transport methods */
+    transports?: AuthenticatorTransport[];
+    /** Timestamp when credential was created */
+    createdAt: Date;
+    /** Timestamp of last successful authentication */
+    lastUsedAt?: Date;
+    /** User-friendly name for the credential */
+    name?: string;
+}
+/**
+ * WebAuthn service for handling FIDO2 registration and authentication
+ *
+ * @example
+ * ```typescript
+ * const webauthn = getWebAuthnService({
+ *   rpName: 'Vorion',
+ *   rpId: 'vorion.ai',
+ *   origin: 'https://vorion.ai'
+ * });
+ *
+ * // Generate registration options
+ * const options = await webauthn.generateRegistrationOpts(
+ *   'user-123',
+ *   'john@vorion.ai'
+ * );
+ *
+ * // After user completes registration on client
+ * const credential = await webauthn.verifyRegistration(
+ *   'user-123',
+ *   clientResponse,
+ *   expectedChallenge
+ * );
+ * ```
+ */
+export declare class WebAuthnService {
+    private readonly config;
+    private readonly challengeStore;
+    /**
+     * Create a new WebAuthn service instance
+     * @param config - Partial configuration (merged with defaults)
+     */
+    constructor(config?: Partial<WebAuthnConfig>);
+    /**
+     * Generate registration options for a new WebAuthn credential
+     *
+     * Creates the necessary options for the WebAuthn navigator.credentials.create() call.
+     * Excludes any existing credentials to prevent duplicate registration.
+     *
+     * @param userId - Unique user identifier
+     * @param userName - Human-readable user name (usually email)
+     * @param existingCredentials - User's existing credentials to exclude
+     * @returns PublicKeyCredentialCreationOptionsJSON for client-side registration
+     *
+     * @example
+     * ```typescript
+     * const options = await service.generateRegistrationOpts(
+     *   'user-123',
+     *   'john@vorion.ai',
+     *   existingCredentials
+     * );
+     * // Send options to client for navigator.credentials.create()
+     * ```
+     */
+    generateRegistrationOpts(userId: string, userName: string, existingCredentials?: WebAuthnCredential[]): Promise<PublicKeyCredentialCreationOptionsJSON>;
+    /**
+     * Verify a registration response from the client
+     *
+     * Validates the attestation and creates a new credential record.
+     *
+     * @param userId - User identifier (must match the one used in generateRegistrationOpts)
+     * @param response - Registration response from navigator.credentials.create()
+     * @param expectedChallenge - The challenge that was sent to the client
+     * @returns The verified WebAuthn credential to store
+     * @throws Error if verification fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const credential = await service.verifyRegistration(
+     *     'user-123',
+     *     clientResponse,
+     *     storedChallenge
+     *   );
+     *   // Save credential to database
+     * } catch (error) {
+     *   console.error('Registration failed:', error.message);
+     * }
+     * ```
+     */
+    verifyRegistration(userId: string, response: RegistrationResponseJSON, expectedChallenge: string): Promise<WebAuthnCredential>;
+    /**
+     * Generate authentication options for WebAuthn login
+     *
+     * Creates options for navigator.credentials.get() call.
+     *
+     * @param existingCredentials - User's registered credentials
+     * @returns PublicKeyCredentialRequestOptionsJSON for client-side authentication
+     *
+     * @example
+     * ```typescript
+     * const options = await service.generateAuthenticationOpts(userCredentials);
+     * // Send options to client for navigator.credentials.get()
+     * ```
+     */
+    generateAuthenticationOpts(existingCredentials: WebAuthnCredential[]): Promise<PublicKeyCredentialRequestOptionsJSON>;
+    /**
+     * Verify an authentication response from the client
+     *
+     * Validates the assertion and checks the signature counter to prevent replay attacks.
+     *
+     * @param credential - The stored credential being used
+     * @param response - Authentication response from navigator.credentials.get()
+     * @param expectedChallenge - The challenge that was sent to the client
+     * @returns Object containing verification status and new counter value
+     * @throws Error if verification fails
+     *
+     * @example
+     * ```typescript
+     * const result = await service.verifyAuthentication(
+     *   storedCredential,
+     *   clientResponse,
+     *   storedChallenge
+     * );
+     *
+     * if (result.verified) {
+     *   // Update credential counter in database
+     *   credential.counter = result.newCounter;
+     *   credential.lastUsedAt = new Date();
+     * }
+     * ```
+     */
+    verifyAuthentication(credential: WebAuthnCredential, response: AuthenticationResponseJSON, expectedChallenge: string): Promise<{
+        verified: boolean;
+        newCounter: number;
+    }>;
+    /**
+     * Get a stored challenge for a user (consumes the challenge)
+     * @param userId - User identifier
+     * @returns The stored challenge or undefined if not found/expired
+     */
+    getStoredChallenge(userId: string): string | undefined;
+    /**
+     * Generate a unique credential ID
+     */
+    private generateCredentialId;
+    /**
+     * Convert Uint8Array to base64url string
+     */
+    private uint8ArrayToBase64Url;
+    /**
+     * Convert base64url string to Uint8Array
+     */
+    private base64UrlToUint8Array;
+}
+/**
+ * Factory function to create a WebAuthn service instance
+ *
+ * @param config - Partial WebAuthn configuration (merged with defaults)
+ * @returns Configured WebAuthnService instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const webauthn = getWebAuthnService();
+ *
+ * // Custom configuration
+ * const webauthn = getWebAuthnService({
+ *   rpName: 'My App',
+ *   rpId: 'myapp.com',
+ *   origin: 'https://myapp.com',
+ *   userVerification: 'required',
+ * });
+ * ```
+ */
+export declare function getWebAuthnService(config?: Partial<WebAuthnConfig>): WebAuthnService;
+export default WebAuthnService;
+//# sourceMappingURL=webauthn.d.ts.map

package/dist/auth/mfa/webauthn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webauthn.d.ts","sourceRoot":"","sources":["../../../src/auth/mfa/webauthn.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,OAAO,KAAK,EACV,sCAAsC,EACtC,qCAAqC,EACrC,wBAAwB,EACxB,0BAA0B,EAC1B,4BAA4B,EAC7B,MAAM,uBAAuB,CAAC;AAK/B;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,oCAAoC;IACpC,gBAAgB,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;IAC3D,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,UAAU,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACtC,4CAA4C;IAC5C,SAAS,EAAE,IAAI,CAAC;IAChB,kDAAkD;IAClD,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD;;;OAGG;gBACS,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM;IAShD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,wBAAwB,CAC5B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,mBAAmB,GAAE,kBAAkB,EAAO,GAC7C,OAAO,CAAC,sCAAsC,CAAC;IAmClD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,wBAAwB,EAClC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,kBAAkB,CAAC;IAiD9B;;;;;;;;;;;;;OAaG;IACG,0BAA0B,CAC9B,mBAAmB,EAAE,kBAAkB,EAAE,GACxC,OAAO,CAAC,qCAAqC,CAAC;IAmCjD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,oBAAoB,CACxB,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,0BAA0B,EACpC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAwDrD;;;;OAIG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAItD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAK9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,eAAe,CAExF;AAED,eAAe,eAAe,CAAC"}