@breadstone/archipel-platform-authentication 0.0.1

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

@@ -0,0 +1,23 @@
+import { ConfigService } from '@breadstone/archipel-platform-core';
+/**
+ * Provides AES-GCM encryption for MFA secrets.
+ *
+ * @public
+ */
+export declare class MfaEncryptionService {
+    private readonly _key;
+    constructor(configService: ConfigService);
+    /**
+     * Encrypts the provided secret using AES-256-GCM.
+     *
+     * @param secret Plaintext secret to encrypt.
+     * @returns Base64 encoded payload containing IV, auth tag, and ciphertext.
+     */
+    encrypt(secret: string): string;
+    /**
+     * Decrypts the payload produced by {@link encrypt}.
+     *
+     * @param payload Base64 encoded payload with IV, auth tag, and ciphertext.
+     */
+    decrypt(payload: string): string;
+}

package/src/services/mfa/MfaEncryptionService.js

@@ -0,0 +1,59 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MfaEncryptionService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const archipel_platform_core_1 = require("@breadstone/archipel-platform-core");
+const node_crypto_1 = require("node:crypto");
+// #endregion
+/**
+ * Provides AES-GCM encryption for MFA secrets.
+ *
+ * @public
+ */
+let MfaEncryptionService = class MfaEncryptionService {
+    // #endregion
+    // #region Ctor
+    constructor(configService) {
+        const rawKey = configService.tryGet('AUTH_MFA_ENCRYPTION_KEY', '');
+        const material = rawKey && rawKey.length > 0 ? rawKey : 'strivio-mfa-default-key';
+        this._key = (0, node_crypto_1.createHash)('sha256').update(material).digest();
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Encrypts the provided secret using AES-256-GCM.
+     *
+     * @param secret Plaintext secret to encrypt.
+     * @returns Base64 encoded payload containing IV, auth tag, and ciphertext.
+     */
+    encrypt(secret) {
+        const iv = (0, node_crypto_1.randomBytes)(12);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', this._key, iv);
+        const encrypted = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        return Buffer.concat([iv, authTag, encrypted]).toString('base64');
+    }
+    /**
+     * Decrypts the payload produced by {@link encrypt}.
+     *
+     * @param payload Base64 encoded payload with IV, auth tag, and ciphertext.
+     */
+    decrypt(payload) {
+        const buffer = Buffer.from(payload, 'base64');
+        const iv = buffer.subarray(0, 12);
+        const authTag = buffer.subarray(12, 28);
+        const ciphertext = buffer.subarray(28);
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', this._key, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString('utf8');
+    }
+};
+exports.MfaEncryptionService = MfaEncryptionService;
+exports.MfaEncryptionService = MfaEncryptionService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_core_1.ConfigService])
+], MfaEncryptionService);
+//# sourceMappingURL=MfaEncryptionService.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Represents per-channel MFA configuration persisted on the user.
+ *
+ * @public
+ */
+export interface IUserMfaChannelState {
+    enabled: boolean;
+    secret?: string;
+    phoneNumber?: string;
+    email?: string;
+    codeHash?: string;
+    codeExpiresAt?: string;
+    lastSentAt?: string;
+    verifiedAt?: string;
+}
+/**
+ * Represents the full MFA state payload stored with the user.
+ *
+ * @public
+ */
+export interface IUserMfaState {
+    preferredMethod?: string;
+    channels: Record<string, IUserMfaChannelState>;
+    trustedDevices?: string[];
+}
+/**
+ * Optional channel-specific setup context.
+ */
+export interface IMfaSetupContext {
+    phoneNumber?: string;
+    email?: string;
+}
+/**
+ * Normalizes a raw persisted MFA blob into a usable state object.
+ *
+ * @param raw Raw value from persistence.
+ */
+export declare function resolveMfaState(raw: unknown): IUserMfaState;

package/src/services/mfa/MfaState.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMfaState = resolveMfaState;
+/**
+ * Normalizes a raw persisted MFA blob into a usable state object.
+ *
+ * @param raw Raw value from persistence.
+ */
+function resolveMfaState(raw) {
+    if (raw && typeof raw === 'object' && 'channels' in raw) {
+        const typed = raw;
+        return {
+            preferredMethod: typed.preferredMethod,
+            channels: typed.channels ?? {},
+            trustedDevices: typed.trustedDevices ?? []
+        };
+    }
+    return {
+        channels: {},
+        trustedDevices: []
+    };
+}
+//# sourceMappingURL=MfaState.js.map

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

@@ -0,0 +1,4 @@
+/**
+ * Injection token for pluggable MFA channel implementations.
+ */
+export declare const MFA_CHANNELS = "MFA_CHANNELS";

package/src/services/mfa/MfaTokens.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MFA_CHANNELS = void 0;
+/**
+ * Injection token for pluggable MFA channel implementations.
+ */
+exports.MFA_CHANNELS = 'MFA_CHANNELS';
+//# sourceMappingURL=MfaTokens.js.map

package/src/services/mfa/channels/EmailOtpMfaChannel.d.ts

@@ -0,0 +1,21 @@
+import { BcryptService, ConfigService } from '@breadstone/archipel-platform-core';
+import { MfaSubjectPort } from '../../../contracts/MfaSubjectPort';
+import { IMfaSetup } from '../../../models';
+import { IMfaChannel } from '../IMfaChannel';
+import { IMfaSetupContext } from '../MfaState';
+export declare class EmailOtpMfaChannel implements IMfaChannel {
+    readonly method = "email";
+    private readonly _mfaSubject;
+    private readonly _configService;
+    private readonly _bcryptService;
+    private readonly _logger;
+    private readonly _ttlMilliseconds;
+    private readonly _minResendMilliseconds;
+    constructor(mfaSubject: MfaSubjectPort, configService: ConfigService, bcryptService: BcryptService);
+    initSetup(userId: string, context?: IMfaSetupContext): Promise<IMfaSetup>;
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    verifyChallenge(userId: string, code: string): Promise<boolean>;
+    issueChallenge(userId: string): Promise<void>;
+    private verifyCodeAndMaybeEnable;
+    private generateCode;
+}

package/src/services/mfa/channels/EmailOtpMfaChannel.js

@@ -0,0 +1,152 @@
+"use strict";
+// #region Imports
+var EmailOtpMfaChannel_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailOtpMfaChannel = 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 MfaState_1 = require("../MfaState");
+// #endregion
+let EmailOtpMfaChannel = EmailOtpMfaChannel_1 = class EmailOtpMfaChannel {
+    constructor(mfaSubject, configService, bcryptService) {
+        this.method = 'email';
+        this._logger = new common_1.Logger(EmailOtpMfaChannel_1.name);
+        this._mfaSubject = mfaSubject;
+        this._configService = configService;
+        this._bcryptService = bcryptService;
+        this._ttlMilliseconds = archipel_platform_core_1.DateTimeUtils.parse(this._configService.tryGet('AUTH_MFA_EMAIL_CODE_TTL', '10m'));
+        this._minResendMilliseconds = archipel_platform_core_1.DateTimeUtils.parse(this._configService.tryGet('AUTH_MFA_EMAIL_MIN_RESEND', '30s'));
+    }
+    async initSetup(userId, context) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const email = context?.email ?? user.email;
+        if (!email) {
+            throw new common_1.BadRequestException('Email is required for email MFA');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method] ?? { enabled: false };
+        const now = Date.now();
+        if (channel.lastSentAt && now - Date.parse(channel.lastSentAt) < this._minResendMilliseconds) {
+            throw new common_1.BadRequestException('OTP recently sent. Please wait before requesting another code.');
+        }
+        const code = this.generateCode();
+        const hashed = await this._bcryptService.hash(code);
+        state.channels[this.method] = {
+            enabled: false,
+            email: email,
+            codeHash: hashed,
+            codeExpiresAt: new Date(now + this._ttlMilliseconds).toISOString(),
+            lastSentAt: new Date(now).toISOString(),
+        };
+        state.preferredMethod = state.preferredMethod ?? this.method;
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaChannels: state,
+            mfaPreferredMethod: state.preferredMethod,
+            mfaUpdatedAt: new Date(),
+        });
+        this._logger.log(`Sending Email MFA code to ${email} (mock): ${code}`);
+        return {
+            method: this.method,
+        };
+    }
+    async verifySetup(userId, code) {
+        return this.verifyCodeAndMaybeEnable(userId, code, true);
+    }
+    async verifyChallenge(userId, code) {
+        return this.verifyCodeAndMaybeEnable(userId, code, false);
+    }
+    async issueChallenge(userId) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method];
+        if (!channel?.enabled) {
+            throw new common_1.UnauthorizedException('Email MFA is not enabled');
+        }
+        const email = channel.email ?? user.email;
+        if (!email) {
+            throw new common_1.BadRequestException('Email is required for email MFA');
+        }
+        const now = Date.now();
+        if (channel.lastSentAt && now - Date.parse(channel.lastSentAt) < this._minResendMilliseconds) {
+            throw new common_1.BadRequestException('OTP recently sent. Please wait before requesting another code.');
+        }
+        const code = this.generateCode();
+        const hashed = await this._bcryptService.hash(code);
+        state.channels[this.method] = {
+            ...channel,
+            email: email,
+            codeHash: hashed,
+            codeExpiresAt: new Date(now + this._ttlMilliseconds).toISOString(),
+            lastSentAt: new Date(now).toISOString(),
+        };
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaChannels: state,
+            mfaUpdatedAt: new Date(),
+        });
+        this._logger.log(`Sending Email MFA code to ${email} (login): ${code}`);
+    }
+    async verifyCodeAndMaybeEnable(userId, code, enable) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method];
+        if (!channel?.codeHash || !channel.codeExpiresAt) {
+            throw new common_1.UnauthorizedException('Email code not issued');
+        }
+        if (Date.parse(channel.codeExpiresAt) < Date.now()) {
+            throw new common_1.UnauthorizedException('Email code expired');
+        }
+        const isValid = await this._bcryptService.compare(code, channel.codeHash);
+        if (!isValid) {
+            return false;
+        }
+        if (enable) {
+            state.channels[this.method] = {
+                ...channel,
+                enabled: true,
+                verifiedAt: new Date().toISOString(),
+                codeHash: undefined,
+                codeExpiresAt: undefined,
+            };
+            await this._mfaSubject.updateMfaState(userId, {
+                mfaChannels: state,
+                mfaEnabled: true,
+                mfaPreferredMethod: state.preferredMethod ?? this.method,
+                mfaVerifiedAt: new Date(),
+                mfaUpdatedAt: new Date(),
+            });
+        }
+        else {
+            state.channels[this.method] = {
+                ...channel,
+                codeHash: undefined,
+                codeExpiresAt: undefined,
+            };
+            await this._mfaSubject.updateMfaState(userId, {
+                mfaChannels: state,
+                mfaUpdatedAt: new Date(),
+            });
+        }
+        return true;
+    }
+    generateCode() {
+        return (0, node_crypto_1.randomInt)(100000, 999999).toString();
+    }
+};
+exports.EmailOtpMfaChannel = EmailOtpMfaChannel;
+exports.EmailOtpMfaChannel = EmailOtpMfaChannel = EmailOtpMfaChannel_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [MfaSubjectPort_1.MfaSubjectPort, archipel_platform_core_1.ConfigService, archipel_platform_core_1.BcryptService])
+], EmailOtpMfaChannel);
+//# sourceMappingURL=EmailOtpMfaChannel.js.map

package/src/services/mfa/channels/PushMfaChannel.d.ts

@@ -0,0 +1,25 @@
+import { BcryptService, ConfigService } from '@breadstone/archipel-platform-core';
+import { MfaSubjectPort } from '../../../contracts/MfaSubjectPort';
+import { IMfaSetup } from '../../../models';
+import { IMfaChannel } from '../IMfaChannel';
+import { IMfaSetupContext } from '../MfaState';
+/**
+ * Simplified push-style MFA channel that simulates a device approval code.
+ * This is intentionally minimal so it can be replaced by a real push provider later.
+ */
+export declare class PushMfaChannel implements IMfaChannel {
+    readonly method = "push";
+    private readonly _mfaSubject;
+    private readonly _configService;
+    private readonly _bcryptService;
+    private readonly _logger;
+    private readonly _ttlMilliseconds;
+    private readonly _minResendMilliseconds;
+    constructor(mfaSubject: MfaSubjectPort, configService: ConfigService, bcryptService: BcryptService);
+    initSetup(userId: string, _context?: IMfaSetupContext): Promise<IMfaSetup>;
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    verifyChallenge(userId: string, code: string): Promise<boolean>;
+    issueChallenge(userId: string): Promise<void>;
+    private verifyCodeAndMaybeEnable;
+    private generateCode;
+}

package/src/services/mfa/channels/PushMfaChannel.js

@@ -0,0 +1,150 @@
+"use strict";
+// #region Imports
+var PushMfaChannel_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushMfaChannel = 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 MfaState_1 = require("../MfaState");
+// #endregion
+/**
+ * Simplified push-style MFA channel that simulates a device approval code.
+ * This is intentionally minimal so it can be replaced by a real push provider later.
+ */
+let PushMfaChannel = PushMfaChannel_1 = class PushMfaChannel {
+    // #endregion
+    // #region Ctor
+    constructor(mfaSubject, configService, bcryptService) {
+        // #region Fields
+        this.method = 'push';
+        this._logger = new common_1.Logger(PushMfaChannel_1.name);
+        this._mfaSubject = mfaSubject;
+        this._configService = configService;
+        this._bcryptService = bcryptService;
+        this._ttlMilliseconds = archipel_platform_core_1.DateTimeUtils.parse(this._configService.tryGet('AUTH_MFA_PUSH_CODE_TTL', '10m'));
+        this._minResendMilliseconds = archipel_platform_core_1.DateTimeUtils.parse(this._configService.tryGet('AUTH_MFA_PUSH_MIN_RESEND', '30s'));
+    }
+    // #endregion
+    // #region Methods
+    async initSetup(userId, _context) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method] ?? { enabled: false };
+        const now = Date.now();
+        if (channel.lastSentAt && now - Date.parse(channel.lastSentAt) < this._minResendMilliseconds) {
+            throw new common_1.BadRequestException('Approval request recently sent. Please wait before requesting another code.');
+        }
+        const code = this.generateCode();
+        const hashed = await this._bcryptService.hash(code);
+        state.channels[this.method] = {
+            enabled: false,
+            codeHash: hashed,
+            codeExpiresAt: new Date(now + this._ttlMilliseconds).toISOString(),
+            lastSentAt: new Date(now).toISOString(),
+        };
+        state.preferredMethod = state.preferredMethod ?? this.method;
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaChannels: state,
+            mfaPreferredMethod: state.preferredMethod,
+            mfaUpdatedAt: new Date(),
+        });
+        // Replace with actual push notification send once available.
+        this._logger.log(`Simulating push approval code for user ${user.id}: ${code}`);
+        return { method: this.method };
+    }
+    async verifySetup(userId, code) {
+        return this.verifyCodeAndMaybeEnable(userId, code, true);
+    }
+    async verifyChallenge(userId, code) {
+        return this.verifyCodeAndMaybeEnable(userId, code, false);
+    }
+    async issueChallenge(userId) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method];
+        if (!channel?.enabled) {
+            throw new common_1.UnauthorizedException('Push MFA is not enabled');
+        }
+        const now = Date.now();
+        if (channel.lastSentAt && now - Date.parse(channel.lastSentAt) < this._minResendMilliseconds) {
+            throw new common_1.BadRequestException('Approval request recently sent. Please wait before requesting another code.');
+        }
+        const code = this.generateCode();
+        const hashed = await this._bcryptService.hash(code);
+        state.channels[this.method] = {
+            ...channel,
+            codeHash: hashed,
+            codeExpiresAt: new Date(now + this._ttlMilliseconds).toISOString(),
+            lastSentAt: new Date(now).toISOString(),
+        };
+        await this._mfaSubject.updateMfaState(userId, {
+            mfaChannels: state,
+            mfaUpdatedAt: new Date(),
+        });
+        this._logger.log(`Simulating push approval for user ${user.id}: ${code}`);
+    }
+    async verifyCodeAndMaybeEnable(userId, code, enable) {
+        const user = await this._mfaSubject.findById(userId);
+        if (!user) {
+            throw new common_1.BadRequestException('User not found');
+        }
+        const state = (0, MfaState_1.resolveMfaState)(user.mfaChannels);
+        const channel = state.channels[this.method];
+        if (!channel?.codeHash || !channel.codeExpiresAt) {
+            throw new common_1.UnauthorizedException('Push approval not issued');
+        }
+        if (Date.parse(channel.codeExpiresAt) < Date.now()) {
+            throw new common_1.UnauthorizedException('Push approval expired');
+        }
+        const isValid = await this._bcryptService.compare(code, channel.codeHash);
+        if (!isValid) {
+            return false;
+        }
+        if (enable) {
+            state.channels[this.method] = {
+                ...channel,
+                enabled: true,
+                verifiedAt: new Date().toISOString(),
+                codeHash: undefined,
+                codeExpiresAt: undefined,
+            };
+            await this._mfaSubject.updateMfaState(userId, {
+                mfaChannels: state,
+                mfaEnabled: true,
+                mfaPreferredMethod: state.preferredMethod ?? this.method,
+                mfaVerifiedAt: new Date(),
+                mfaUpdatedAt: new Date(),
+            });
+        }
+        else {
+            state.channels[this.method] = {
+                ...channel,
+                codeHash: undefined,
+                codeExpiresAt: undefined,
+            };
+            await this._mfaSubject.updateMfaState(userId, {
+                mfaChannels: state,
+                mfaUpdatedAt: new Date(),
+            });
+        }
+        return true;
+    }
+    generateCode() {
+        return (0, node_crypto_1.randomInt)(100000, 999999).toString();
+    }
+};
+exports.PushMfaChannel = PushMfaChannel;
+exports.PushMfaChannel = PushMfaChannel = PushMfaChannel_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [MfaSubjectPort_1.MfaSubjectPort, archipel_platform_core_1.ConfigService, archipel_platform_core_1.BcryptService])
+], PushMfaChannel);
+//# sourceMappingURL=PushMfaChannel.js.map

package/src/services/mfa/channels/SmsMfaChannel.d.ts

@@ -0,0 +1,21 @@
+import { BcryptService, ConfigService } from '@breadstone/archipel-platform-core';
+import { MfaSubjectPort } from '../../../contracts/MfaSubjectPort';
+import { IMfaSetup } from '../../../models';
+import { IMfaChannel } from '../IMfaChannel';
+import { IMfaSetupContext } from '../MfaState';
+export declare class SmsMfaChannel implements IMfaChannel {
+    readonly method = "sms";
+    private readonly _mfaSubject;
+    private readonly _configService;
+    private readonly _bcryptService;
+    private readonly _logger;
+    private readonly _ttlMilliseconds;
+    private readonly _minResendMilliseconds;
+    constructor(mfaSubject: MfaSubjectPort, configService: ConfigService, bcryptService: BcryptService);
+    initSetup(userId: string, context?: IMfaSetupContext): Promise<IMfaSetup>;
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    verifyChallenge(userId: string, code: string): Promise<boolean>;
+    issueChallenge(userId: string): Promise<void>;
+    private verifyCodeAndMaybeEnable;
+    private generateCode;
+}