@breadstone/archipel-platform-authentication 0.0.1

package/src/services/MfaService.js

@@ -0,0 +1,251 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MfaService = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const MfaSubjectPort_1 = require("../contracts/MfaSubjectPort");
+const MfaEncryptionService_1 = require("./mfa/MfaEncryptionService");
+const MfaState_1 = require("./mfa/MfaState");
+const MfaTokens_1 = require("./mfa/MfaTokens");
+// #endregion
+/**
+ * Orchestrates MFA channels, backup codes, and user preferences.
+ *
+ * @public
+ */
+let MfaService = class MfaService {
+    // #endregion
+    // #region Ctor
+    constructor(bcryptService, mfaSubject, encryptionService, channels) {
+        this._bcryptService = bcryptService;
+        this._mfaSubject = mfaSubject;
+        this._channels = new Map(channels.map((channel) => [channel.method, channel]));
+        this._backupCodeCount = 10;
+        this._encryptionService = encryptionService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Initializes setup for a specific MFA method.
+     */
+    async initSetup(userId, method, context) {
+        const channel = this.requireChannel(method);
+        const user = await this.getUser(userId);
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        if (state.channels[method]?.enabled) {
+            throw new common_1.BadRequestException('Selected MFA method is already enabled');
+        }
+        if (state.channels[method]?.enabled) {
+            throw new common_1.BadRequestException('Selected MFA method is already enabled');
+        }
+        return channel.initSetup(userId, context);
+    }
+    /**
+     * Verifies the initial code for a method and issues backup codes.
+     */
+    async verifySetup(userId, method, code) {
+        const channel = this.requireChannel(method);
+        if (!code?.trim()) {
+            throw new common_1.BadRequestException('A verification code is required');
+        }
+        const isValid = await channel.verifySetup(userId, code.trim());
+        if (!isValid) {
+            throw new common_1.UnauthorizedException('Invalid verification code');
+        }
+        const backupCodes = await this.generateBackupCodes(userId);
+        const latestUser = await this.getUser(userId);
+        const latestState = (0, MfaState_1.resolveMfaState)(latestUser.mfaChannels);
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaEnabled: true,
+            mfaPreferredMethod: latestState.preferredMethod ?? method,
+            mfaBackupCodes: backupCodes.hashed,
+            mfaVerifiedAt: new Date(),
+            mfaUpdatedAt: new Date(),
+            mfaChannels: latestState,
+        });
+        return { backupCodes: backupCodes.plain };
+    }
+    /**
+     * Verifies a login challenge using the selected method or backup code.
+     */
+    async verifyChallenge(userId, method, code) {
+        const sanitizedCode = code.trim();
+        const user = await this.getUser(userId);
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        if (!user.mfaEnabled) {
+            throw new common_1.BadRequestException('Multi-factor authentication is not enabled');
+        }
+        if (method === 'backup') {
+            const success = await this.tryConsumeBackupCode(user, sanitizedCode);
+            if (success) {
+                await this.touchVerification(userId);
+            }
+            return success;
+        }
+        const channel = this.requireChannel(method);
+        const enabledMethods = Object.entries(state.channels)
+            .filter(([, value]) => value.enabled)
+            .map(([key]) => key);
+        if (!enabledMethods.includes(method)) {
+            throw new common_1.UnauthorizedException('Selected method is not enabled');
+        }
+        const isValid = await channel.verifyChallenge(userId, sanitizedCode);
+        if (isValid) {
+            await this.touchVerification(userId);
+            return true;
+        }
+        const fallback = await this.tryConsumeBackupCode(user, sanitizedCode);
+        if (fallback) {
+            await this.touchVerification(userId);
+        }
+        return fallback;
+    }
+    /**
+     * Returns enabled methods and preferred method for a user.
+     */
+    async getEnabledMethods(userId) {
+        const user = await this.getUser(userId);
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const methods = Object.entries(state.channels)
+            .filter(([, value]) => value.enabled)
+            .map(([key]) => key);
+        if (methods.length === 0 && this._channels.has('totp') && user.mfaSecret) {
+            state.channels['totp'] = {
+                enabled: true,
+                secret: this._encryptionService.encrypt(user.mfaSecret),
+                verifiedAt: user.mfaVerifiedAt?.toISOString() ?? new Date().toISOString(),
+            };
+            state.preferredMethod = state.preferredMethod ?? 'totp';
+            await this._mfaSubject.updateMfaState(userId, {
+                mfaChannels: state,
+                mfaPreferredMethod: state.preferredMethod,
+                mfaSecret: null,
+                mfaUpdatedAt: new Date(),
+            });
+            methods.push('totp');
+        }
+        const preferredFromUser = user.mfaPreferredMethod;
+        return {
+            methods: methods,
+            preferredMethod: state.preferredMethod ?? preferredFromUser ?? methods[0],
+        };
+    }
+    /**
+     * Issues out-of-band challenge codes for login flows for applicable channels.
+     */
+    async issueChallenges(userId, methods) {
+        const uniqueMethods = Array.from(new Set(methods));
+        for (const method of uniqueMethods) {
+            const channel = this._channels.get(method);
+            if (!channel?.issueChallenge) {
+                continue;
+            }
+            await channel.issueChallenge(userId);
+        }
+    }
+    /**
+     * Updates the preferred MFA method.
+     */
+    async setPreferredMethod(userId, method) {
+        const enabled = await this.getEnabledMethods(userId);
+        if (!enabled.methods.includes(method)) {
+            throw new common_1.BadRequestException('Preferred method must be enabled');
+        }
+        const user = await this.getUser(userId);
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        state.preferredMethod = method;
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaPreferredMethod: method,
+            mfaChannels: state,
+            mfaUpdatedAt: new Date(),
+        });
+    }
+    /**
+     * Regenerates backup codes.
+     */
+    async regenerateBackupCodes(userId) {
+        const user = await this.getUser(userId);
+        if (!user.mfaEnabled) {
+            throw new common_1.BadRequestException('Multi-factor authentication is not enabled');
+        }
+        const backupCodes = await this.generateBackupCodes(userId);
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaBackupCodes: backupCodes.hashed,
+            mfaUpdatedAt: new Date(),
+        });
+        return backupCodes.plain;
+    }
+    /**
+     * Disables MFA for a user and clears channel secrets.
+     */
+    async disable(userId) {
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaEnabled: false,
+            mfaPreferredMethod: null,
+            mfaBackupCodes: [],
+            mfaChannels: { channels: {}, trustedDevices: [] },
+            mfaSecret: null,
+            mfaVerifiedAt: null,
+            mfaUpdatedAt: new Date(),
+        });
+    }
+    get registeredMethods() {
+        return Array.from(this._channels.keys());
+    }
+    requireChannel(method) {
+        const channel = this._channels.get(method);
+        if (!channel) {
+            throw new common_1.BadRequestException(`Unsupported MFA method: ${method}`);
+        }
+        return channel;
+    }
+    async generateBackupCodes(userId) {
+        const plain = Array.from({ length: this._backupCodeCount }, () => (0, node_crypto_1.randomBytes)(5).toString('hex'));
+        const hashed = await Promise.all(plain.map((value) => this._bcryptService.hash(value)));
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaBackupCodes: hashed,
+            mfaUpdatedAt: new Date(),
+        });
+        return { plain, hashed };
+    }
+    async tryConsumeBackupCode(user, code) {
+        const storedBackupCodes = user.mfaBackupCodes ?? [];
+        for (const storedBackupCode of storedBackupCodes) {
+            const isMatch = await this._bcryptService.compare(code, storedBackupCode);
+            if (isMatch) {
+                const remainingCodes = storedBackupCodes.filter((value) => value !== storedBackupCode);
+                await this._mfaSubject.updateMfaState(user.id, {
+                    mfaBackupCodes: remainingCodes,
+                    mfaUpdatedAt: new Date(),
+                });
+                return true;
+            }
+        }
+        return false;
+    }
+    async getUser(userId) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        return user;
+    }
+    async touchVerification(userId) {
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaVerifiedAt: new Date(),
+            mfaUpdatedAt: new Date(),
+        });
+    }
+};
+exports.MfaService = MfaService;
+exports.MfaService = MfaService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(3, (0, common_1.Inject)(MfaTokens_1.MFA_CHANNELS)),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_core_1.BcryptService,
+        MfaSubjectPort_1.MfaSubjectPort,
+        MfaEncryptionService_1.MfaEncryptionService, Array])
+], MfaService);
+//# sourceMappingURL=MfaService.js.map

package/src/services/SessionService.d.ts

@@ -0,0 +1,66 @@
+import type { IDeviceInfo } from '@breadstone/archipel-platform-core';
+import { MappingService } from '@breadstone/archipel-platform-core';
+import { SessionPersistencePort } from '../contracts/SessionPersistencePort';
+import { SessionResponse } from '../models';
+/**
+ * Manages user sessions via the {@link SessionPersistencePort}.
+ *
+ * @public
+ */
+export declare class SessionService {
+    private readonly _sessionPersistence;
+    private readonly _mappingService;
+    /**
+     * Constructs a new instance of the `SessionService` class.
+     *
+     * @public
+     * @param sessionPersistence - The session persistence port.
+     * @param mappingService - The mapping service.
+     */
+    constructor(sessionPersistence: SessionPersistencePort, mappingService: MappingService);
+    /**
+     * Stores or updates a session.
+     *
+     * @public
+     * @param token - The session token.
+     * @param userId - The user identifier.
+     * @param ipAddress - The client IP address.
+     * @param deviceInfo - Optional device information.
+     * @param location - Optional geolocation string.
+     * @param clientName - Optional client application name.
+     */
+    store(token: string, userId: string, ipAddress: string, deviceInfo?: IDeviceInfo, location?: string, clientName?: string): Promise<void>;
+    /**
+     * Updates the last-active timestamp for a session.
+     *
+     * @public
+     * @param token - The session token.
+     */
+    updateLastActive(token: string): Promise<void>;
+    /**
+     * Lists all sessions for a user, marking the current one.
+     *
+     * @public
+     * @param userId - The user identifier.
+     * @param token - The current session token.
+     * @returns Array of session responses.
+     */
+    listSessions(userId: string, token: string): Promise<Array<SessionResponse>>;
+    /**
+     * Invalidates a session by its record id.
+     *
+     * @public
+     * @param sessionId - The session record identifier.
+     * @param userId - The owning user identifier.
+     * @returns `true` if a session was invalidated.
+     */
+    invalidateById(sessionId: string, userId: string): Promise<boolean>;
+    /**
+     * Invalidates a session by its token.
+     *
+     * @public
+     * @param token - The session token.
+     * @returns `true` if a session was invalidated.
+     */
+    invalidate(token: string): Promise<boolean>;
+}

package/src/services/SessionService.js

@@ -0,0 +1,108 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionService = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
+const common_1 = require("@nestjs/common");
+const SessionPersistencePort_1 = require("../contracts/SessionPersistencePort");
+const SessionMappingProfile_1 = require("../mappers/SessionMappingProfile");
+// #endregion
+/**
+ * Manages user sessions via the {@link SessionPersistencePort}.
+ *
+ * @public
+ */
+let SessionService = class SessionService {
+    // #endregion
+    // #region Ctor
+    /**
+     * Constructs a new instance of the `SessionService` class.
+     *
+     * @public
+     * @param sessionPersistence - The session persistence port.
+     * @param mappingService - The mapping service.
+     */
+    constructor(sessionPersistence, mappingService) {
+        this._sessionPersistence = sessionPersistence;
+        this._mappingService = mappingService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Stores or updates a session.
+     *
+     * @public
+     * @param token - The session token.
+     * @param userId - The user identifier.
+     * @param ipAddress - The client IP address.
+     * @param deviceInfo - Optional device information.
+     * @param location - Optional geolocation string.
+     * @param clientName - Optional client application name.
+     */
+    async store(token, userId, ipAddress, deviceInfo, location, clientName) {
+        await this._sessionPersistence.store({
+            token,
+            userId,
+            ipAddress,
+            deviceInfo,
+            location,
+            clientName,
+        });
+    }
+    /**
+     * Updates the last-active timestamp for a session.
+     *
+     * @public
+     * @param token - The session token.
+     */
+    async updateLastActive(token) {
+        const session = await this._sessionPersistence.findByToken(token);
+        if (session) {
+            await this._sessionPersistence.updateLastActive(token, new Date());
+        }
+    }
+    /**
+     * Lists all sessions for a user, marking the current one.
+     *
+     * @public
+     * @param userId - The user identifier.
+     * @param token - The current session token.
+     * @returns Array of session responses.
+     */
+    async listSessions(userId, token) {
+        const result = await this._sessionPersistence.findAllByUserId(userId);
+        const input = result.map((x) => ({
+            isCurrent: x.token === token,
+            session: x,
+        }));
+        return this._mappingService.map(SessionMappingProfile_1.SESSION_LIST_MAPPING_KEY, input);
+    }
+    /**
+     * Invalidates a session by its record id.
+     *
+     * @public
+     * @param sessionId - The session record identifier.
+     * @param userId - The owning user identifier.
+     * @returns `true` if a session was invalidated.
+     */
+    async invalidateById(sessionId, userId) {
+        return this._sessionPersistence.invalidateById(sessionId, userId);
+    }
+    /**
+     * Invalidates a session by its token.
+     *
+     * @public
+     * @param token - The session token.
+     * @returns `true` if a session was invalidated.
+     */
+    async invalidate(token) {
+        return this._sessionPersistence.invalidate(token);
+    }
+};
+exports.SessionService = SessionService;
+exports.SessionService = SessionService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [SessionPersistencePort_1.SessionPersistencePort, archipel_platform_core_1.MappingService])
+], SessionService);
+//# sourceMappingURL=SessionService.js.map

package/src/services/VerificationService.d.ts

@@ -0,0 +1,56 @@
+import { ConfigService, HostService } from '@breadstone/archipel-platform-core';
+import { JwtService } from '@nestjs/jwt';
+import { VerificationSubjectPort } from '../contracts/VerificationSubjectPort';
+/**
+ * Manages email / PIN verification tokens via the {@link VerificationSubjectPort}.
+ *
+ * @public
+ */
+export declare class VerificationService {
+    private readonly _jwtService;
+    private readonly _hostService;
+    private readonly _verificationSubject;
+    private readonly _configService;
+    /**
+     * Constructs a new instance of the `VerificationService` class.
+     *
+     * @public
+     * @param jwtService - JWT service instance.
+     * @param hostService - Host service instance.
+     * @param verificationSubject - Verification subject port.
+     * @param configService - Configuration service instance.
+     */
+    constructor(jwtService: JwtService, hostService: HostService, verificationSubject: VerificationSubjectPort, configService: ConfigService);
+    /**
+     * Exhibits a new verification token.
+     *
+     * @public
+     * @param data - The data to exhibit.
+     * @returns The verification token.
+     */
+    exhibitToken(data: Record<string, string>): Promise<string>;
+    /**
+     * Redeems the user's token.
+     *
+     * @public
+     * @param token - The token to redeem.
+     * @returns The token data.
+     */
+    redeemToken(token: string): Promise<Record<string, string>>;
+    /**
+     * Verifies the user's token.
+     *
+     * @public
+     * @param token - The verification token.
+     */
+    verifyToken(token: string): Promise<boolean>;
+    verifyPin(pin: string, login: string): Promise<boolean>;
+    /**
+     * Constructs the verification link.
+     *
+     * @public
+     * @param token The verification token.
+     * @returns The URL to verify the email.
+     */
+    buildVerificationLink(token: string): string;
+}

package/src/services/VerificationService.js

@@ -0,0 +1,124 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerificationService = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
+const common_1 = require("@nestjs/common");
+const jwt_1 = require("@nestjs/jwt");
+const VerificationSubjectPort_1 = require("../contracts/VerificationSubjectPort");
+// #endregion
+/**
+ * Manages email / PIN verification tokens via the {@link VerificationSubjectPort}.
+ *
+ * @public
+ */
+let VerificationService = class VerificationService {
+    // #endregion
+    // #region Ctor
+    /**
+     * Constructs a new instance of the `VerificationService` class.
+     *
+     * @public
+     * @param jwtService - JWT service instance.
+     * @param hostService - Host service instance.
+     * @param verificationSubject - Verification subject port.
+     * @param configService - Configuration service instance.
+     */
+    constructor(jwtService, hostService, verificationSubject, configService) {
+        this._jwtService = jwtService;
+        this._hostService = hostService;
+        this._verificationSubject = verificationSubject;
+        this._configService = configService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Exhibits a new verification token.
+     *
+     * @public
+     * @param data - The data to exhibit.
+     * @returns The verification token.
+     */
+    exhibitToken(data) {
+        return this._jwtService.signAsync(data, {
+            expiresIn: archipel_platform_core_1.DateTimeUtils.parse(this._configService.get('AUTH_VERIFY_JWT_EXPIRES_IN')),
+        });
+    }
+    /**
+     * Redeems the user's token.
+     *
+     * @public
+     * @param token - The token to redeem.
+     * @returns The token data.
+     */
+    redeemToken(token) {
+        return this._jwtService.verifyAsync(token);
+    }
+    /**
+     * Verifies the user's token.
+     *
+     * @public
+     * @param token - The verification token.
+     */
+    async verifyToken(token) {
+        if (this._jwtService.verify(token)) {
+            const jwt = this._jwtService.decode(token);
+            // check if the token is expired
+            if (jwt.exp && Number(jwt.exp) < Math.floor(Date.now() / 1000)) {
+                throw new common_1.BadRequestException('Invalid or expired token');
+            }
+        }
+        const auth = await this._verificationSubject.findByVerificationToken(token);
+        if (!auth || auth.isVerified) {
+            return false;
+        }
+        await this._verificationSubject.markVerified(auth.id);
+        return true;
+    }
+    async verifyPin(pin, login) {
+        const user = await this._verificationSubject.findByLogin(login);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        if (user.isVerified) {
+            throw new common_1.BadRequestException('User already verified');
+        }
+        if (user.verificationToken) {
+            const jwt = await this.redeemToken(user.verificationToken);
+            if (jwt['email'] !== user.email) {
+                throw new common_1.BadRequestException('Invalid verification token');
+            }
+            if (jwt['pin'] !== pin) {
+                throw new common_1.BadRequestException('Invalid verification token');
+            }
+            if (jwt['exp'] && Number(jwt['exp']) < Math.floor(Date.now() / 1000)) {
+                throw new common_1.BadRequestException('Expired verification token');
+            }
+            if (jwt['pin'] === pin && jwt['email'] === user.email) {
+                await this._verificationSubject.markVerified(user.id);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Constructs the verification link.
+     *
+     * @public
+     * @param token The verification token.
+     * @returns The URL to verify the email.
+     */
+    buildVerificationLink(token) {
+        return `${this._hostService.host}/api/auth/verify-token?token=${token}`; // get this dynamically or from config
+    }
+};
+exports.VerificationService = VerificationService;
+exports.VerificationService = VerificationService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [jwt_1.JwtService,
+        archipel_platform_core_1.HostService,
+        VerificationSubjectPort_1.VerificationSubjectPort,
+        archipel_platform_core_1.ConfigService])
+], VerificationService);
+//# sourceMappingURL=VerificationService.js.map

package/src/services/index.d.ts

@@ -0,0 +1,5 @@
+export * from './AuthTokenService';
+export * from './ChallengeService';
+export * from './MfaService';
+export * from './SessionService';
+export * from './VerificationService';

package/src/services/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./AuthTokenService"), exports);
+tslib_1.__exportStar(require("./ChallengeService"), exports);
+tslib_1.__exportStar(require("./MfaService"), exports);
+tslib_1.__exportStar(require("./SessionService"), exports);
+tslib_1.__exportStar(require("./VerificationService"), exports);
+//# sourceMappingURL=index.js.map

package/src/services/mfa/IMfaChannel.d.ts

@@ -0,0 +1,40 @@
+import { IMfaSetup } from '../../models';
+import { IMfaSetupContext } from './MfaState';
+/**
+ * Defines the contract each MFA channel must implement.
+ *
+ * @public
+ */
+export interface IMfaChannel {
+    /**
+     * Unique identifier of the MFA method (e.g., `totp`, `sms`, `email`).
+     */
+    readonly method: string;
+    /**
+     * Initializes the setup flow for the channel and persists any channel-specific bootstrap state.
+     *
+     * @param userId Identifier of the user starting setup.
+     */
+    initSetup(userId: string, context?: IMfaSetupContext): Promise<IMfaSetup>;
+    /**
+     * Verifies the first setup code and marks the channel as ready for challenges.
+     *
+     * @param userId Identifier of the user finishing setup.
+     * @param code User supplied setup code.
+     */
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    /**
+     * Verifies a challenge code during login.
+     *
+     * @param userId Identifier of the challenged user.
+     * @param code User supplied challenge code.
+     */
+    verifyChallenge(userId: string, code: string): Promise<boolean>;
+    /**
+     * Issues or refreshes a one-time challenge code for out-of-band channels (SMS, email, push).
+     * Channels that do not require pre-issued codes can implement this as a no-op.
+     *
+     * @param userId Identifier of the challenged user.
+     */
+    issueChallenge?(userId: string): Promise<void>;
+}

package/src/services/mfa/IMfaChannel.js

@@ -0,0 +1,4 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IMfaChannel.js.map