@breadstone/archipel-platform-authentication 0.0.1

package/src/models/index.d.ts

@@ -0,0 +1,6 @@
+export * from './IMfaChallengePayload';
+export * from './IMfaConfirmation';
+export * from './IMfaSetup';
+export * from './ISignInResult';
+export * from './JwtPayloadBase';
+export * from './responses';

package/src/models/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./IMfaChallengePayload"), exports);
+tslib_1.__exportStar(require("./IMfaConfirmation"), exports);
+tslib_1.__exportStar(require("./IMfaSetup"), exports);
+tslib_1.__exportStar(require("./ISignInResult"), exports);
+tslib_1.__exportStar(require("./JwtPayloadBase"), exports);
+tslib_1.__exportStar(require("./responses"), exports);
+//# sourceMappingURL=index.js.map

package/src/models/responses/SessionResponse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `SessionResponse` class.
+ *
+ * @public
+ */
+export declare class SessionResponse {
+    id: string;
+    deviceType: string | null;
+    deviceName: string | null;
+    browserName: string | null;
+    browserVersion: string | null;
+    osName: string | null;
+    osVersion: string | null;
+    location: string | null;
+    clientName: string | null;
+    ipAddress: string;
+    lastActive: Date;
+    createdAt: Date;
+    isCurrent: boolean;
+}

package/src/models/responses/SessionResponse.js

@@ -0,0 +1,164 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionResponse = void 0;
+const tslib_1 = require("tslib");
+const swagger_1 = require("@nestjs/swagger");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+// #endregion
+/**
+ * The `SessionResponse` class.
+ *
+ * @public
+ */
+class SessionResponse {
+}
+exports.SessionResponse = SessionResponse;
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Unique session identifier',
+        type: String,
+        example: '507f1f77bcf86cd799439011'
+    }),
+    tslib_1.__metadata("design:type", String)
+], SessionResponse.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Device type',
+        type: String,
+        example: 'desktop',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "deviceType", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Human-readable device name',
+        type: String,
+        example: 'macOS Chrome',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "deviceName", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Browser name',
+        type: String,
+        example: 'Chrome',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "browserName", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Browser version',
+        type: String,
+        example: '120.0.0',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "browserVersion", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Operating system name',
+        type: String,
+        example: 'macOS',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "osName", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Operating system version',
+        type: String,
+        example: '14.0',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "osVersion", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Geographic location',
+        type: String,
+        example: 'Berlin Germany',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "location", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Client application name',
+        type: String,
+        example: 'My Awesome App',
+        nullable: true
+    }),
+    tslib_1.__metadata("design:type", Object)
+], SessionResponse.prototype, "clientName", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'IP address',
+        type: String,
+        example: '192.168.1.1'
+    }),
+    tslib_1.__metadata("design:type", String)
+], SessionResponse.prototype, "ipAddress", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsDate)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Last activity timestamp',
+        type: Date,
+        example: '2025-11-05T10:30:00Z'
+    }),
+    tslib_1.__metadata("design:type", Date)
+], SessionResponse.prototype, "lastActive", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsDate)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Session creation timestamp',
+        type: Date,
+        example: '2025-11-01T08:00:00Z'
+    }),
+    tslib_1.__metadata("design:type", Date)
+], SessionResponse.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsBoolean)(),
+    (0, swagger_1.ApiProperty)({
+        description: 'Indicates if this is the current active session',
+        type: Boolean,
+        example: true
+    }),
+    tslib_1.__metadata("design:type", Boolean)
+], SessionResponse.prototype, "isCurrent", void 0);
+//# sourceMappingURL=SessionResponse.js.map

package/src/models/responses/index.d.ts

@@ -0,0 +1 @@
+export * from './SessionResponse';

package/src/models/responses/index.js

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

package/src/serializer/SessionSerializer.d.ts

@@ -0,0 +1,5 @@
+import { PassportSerializer } from '@nestjs/passport';
+export declare class SessionSerializer extends PassportSerializer {
+    serializeUser(user: unknown, done: (err: Error | null, user: unknown) => void): void;
+    deserializeUser(payload: string, done: (err: Error | null, payload: string) => void): void;
+}

package/src/serializer/SessionSerializer.js

@@ -0,0 +1,23 @@
+"use strict";
+/* eslint-disable no-unused-vars */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionSerializer = void 0;
+const tslib_1 = require("tslib");
+// #region Imports
+const common_1 = require("@nestjs/common");
+const passport_1 = require("@nestjs/passport");
+// #endregion
+let SessionSerializer = class SessionSerializer extends passport_1.PassportSerializer {
+    // #region Methods
+    serializeUser(user, done) {
+        done(null, user);
+    }
+    deserializeUser(payload, done) {
+        done(null, payload);
+    }
+};
+exports.SessionSerializer = SessionSerializer;
+exports.SessionSerializer = SessionSerializer = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], SessionSerializer);
+//# sourceMappingURL=SessionSerializer.js.map

package/src/services/AuthTokenService.d.ts

@@ -0,0 +1,30 @@
+import { JwtService } from '@nestjs/jwt';
+import type { IAuthSubject } from '../contracts/IAuthSubject';
+import { TokenEnricherPort } from '../contracts/TokenEnricherPort';
+/**
+ * Generic service responsible for creating JWT access tokens.
+ * Builds a base payload from {@link IAuthSubject} and optionally enriches it
+ * via the {@link TokenEnricherPort} with product-specific claims.
+ *
+ * @public
+ */
+export declare class AuthTokenService {
+    private readonly _jwtService;
+    private readonly _tokenEnricher;
+    /**
+     * Constructs a new instance of the `AuthTokenService` class.
+     *
+     * @public
+     * @param jwtService - The NestJS JWT service.
+     * @param tokenEnricher - Optional token enricher port.
+     */
+    constructor(jwtService: JwtService, tokenEnricher: TokenEnricherPort | null);
+    /**
+     * Creates a signed JWT for the given subject.
+     *
+     * @public
+     * @param subject - The authenticated subject.
+     * @returns The signed JWT access token.
+     */
+    createAccessToken(subject: IAuthSubject): Promise<string>;
+}

package/src/services/AuthTokenService.js

@@ -0,0 +1,58 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthTokenService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const jwt_1 = require("@nestjs/jwt");
+// #endregion
+/**
+ * Generic service responsible for creating JWT access tokens.
+ * Builds a base payload from {@link IAuthSubject} and optionally enriches it
+ * via the {@link TokenEnricherPort} with product-specific claims.
+ *
+ * @public
+ */
+let AuthTokenService = class AuthTokenService {
+    // #endregion
+    // #region Ctor
+    /**
+     * Constructs a new instance of the `AuthTokenService` class.
+     *
+     * @public
+     * @param jwtService - The NestJS JWT service.
+     * @param tokenEnricher - Optional token enricher port.
+     */
+    constructor(jwtService, tokenEnricher) {
+        this._jwtService = jwtService;
+        this._tokenEnricher = tokenEnricher ?? null;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Creates a signed JWT for the given subject.
+     *
+     * @public
+     * @param subject - The authenticated subject.
+     * @returns The signed JWT access token.
+     */
+    async createAccessToken(subject) {
+        const baseClaims = {
+            id: subject.id,
+            email: subject.email,
+            roles: [...subject.roles],
+        };
+        if (this._tokenEnricher) {
+            const extra = await this._tokenEnricher.enrichClaims(subject);
+            Object.assign(baseClaims, extra);
+        }
+        return this._jwtService.signAsync(baseClaims);
+    }
+};
+exports.AuthTokenService = AuthTokenService;
+exports.AuthTokenService = AuthTokenService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(1, (0, common_1.Optional)()),
+    tslib_1.__metadata("design:paramtypes", [jwt_1.JwtService, Object])
+], AuthTokenService);
+//# sourceMappingURL=AuthTokenService.js.map

package/src/services/ChallengeService.d.ts

@@ -0,0 +1,41 @@
+import { ConfigService } from '@breadstone/archipel-platform-core';
+export interface IMfaChallengeState {
+    id: string;
+    userId: string;
+    allowedMethods: string[];
+    preferredMethod?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    location?: string;
+    clientName?: string;
+    createdAt: Date;
+    expiresAt: Date;
+    attempts: number;
+}
+/**
+ * Stores and validates MFA login challenges.
+ *
+ * @public
+ */
+export declare class ChallengeService {
+    private readonly _ttlMilliseconds;
+    private readonly _maxAttempts;
+    private readonly _challenges;
+    constructor(configService: ConfigService);
+    /**
+     * Issues a new MFA challenge for a user.
+     */
+    create(userId: string, methods: string[], preferredMethod?: string, ipAddress?: string, userAgent?: string, location?: string, clientName?: string): Promise<IMfaChallengeState>;
+    /**
+     * Retrieves an active challenge, throwing if invalid or expired.
+     */
+    get(challengeId: string): Promise<IMfaChallengeState>;
+    /**
+     * Increments failed attempts and optionally invalidates the challenge.
+     */
+    incrementAttempts(challengeId: string): Promise<IMfaChallengeState>;
+    /**
+     * Invalidates a challenge after successful verification.
+     */
+    invalidate(challengeId: string): Promise<void>;
+}

package/src/services/ChallengeService.js

@@ -0,0 +1,89 @@
+"use strict";
+// #region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChallengeService = 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");
+/**
+ * Stores and validates MFA login challenges.
+ *
+ * @public
+ */
+let ChallengeService = class ChallengeService {
+    // #endregion
+    // #region Ctor
+    constructor(configService) {
+        this._ttlMilliseconds = archipel_platform_core_1.DateTimeUtils.parse(configService.tryGet('AUTH_MFA_CHALLENGE_EXPIRES_IN', '5m'));
+        this._maxAttempts = Number(configService.tryGet('AUTH_MFA_MAX_ATTEMPTS', '5'));
+        this._challenges = new Map();
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Issues a new MFA challenge for a user.
+     */
+    async create(userId, methods, preferredMethod, ipAddress, userAgent, location, clientName) {
+        const id = (0, node_crypto_1.randomUUID)();
+        const now = new Date();
+        const challenge = {
+            id: id,
+            userId: userId,
+            allowedMethods: methods,
+            preferredMethod: preferredMethod && methods.includes(preferredMethod) ? preferredMethod : methods[0],
+            ipAddress,
+            userAgent,
+            location,
+            clientName,
+            createdAt: now,
+            expiresAt: new Date(now.getTime() + this._ttlMilliseconds),
+            attempts: 0,
+        };
+        this._challenges.set(id, challenge);
+        return challenge;
+    }
+    /**
+     * Retrieves an active challenge, throwing if invalid or expired.
+     */
+    async get(challengeId) {
+        const challenge = this._challenges.get(challengeId);
+        if (!challenge) {
+            throw new common_1.UnauthorizedException('Invalid MFA challenge');
+        }
+        if (challenge.expiresAt.getTime() <= Date.now()) {
+            this._challenges.delete(challengeId);
+            throw new common_1.UnauthorizedException('MFA challenge expired');
+        }
+        return challenge;
+    }
+    /**
+     * Increments failed attempts and optionally invalidates the challenge.
+     */
+    async incrementAttempts(challengeId) {
+        const challenge = await this.get(challengeId);
+        const attempts = challenge.attempts + 1;
+        const updated = {
+            ...challenge,
+            attempts: attempts,
+        };
+        if (attempts >= this._maxAttempts) {
+            this._challenges.delete(challengeId);
+            throw new common_1.UnauthorizedException('MFA challenge locked after too many attempts');
+        }
+        this._challenges.set(challengeId, updated);
+        return updated;
+    }
+    /**
+     * Invalidates a challenge after successful verification.
+     */
+    async invalidate(challengeId) {
+        this._challenges.delete(challengeId);
+    }
+};
+exports.ChallengeService = ChallengeService;
+exports.ChallengeService = ChallengeService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_core_1.ConfigService])
+], ChallengeService);
+//# sourceMappingURL=ChallengeService.js.map

package/src/services/MfaService.d.ts

@@ -0,0 +1,60 @@
+import { BcryptService } from '@breadstone/archipel-platform-core';
+import { MfaSubjectPort } from '../contracts/MfaSubjectPort';
+import { IMfaConfirmation, IMfaSetup } from '../models';
+import { IMfaChannel } from './mfa/IMfaChannel';
+import { MfaEncryptionService } from './mfa/MfaEncryptionService';
+import { IMfaSetupContext } from './mfa/MfaState';
+/**
+ * Orchestrates MFA channels, backup codes, and user preferences.
+ *
+ * @public
+ */
+export declare class MfaService {
+    private readonly _bcryptService;
+    private readonly _mfaSubject;
+    private readonly _channels;
+    private readonly _backupCodeCount;
+    private readonly _encryptionService;
+    constructor(bcryptService: BcryptService, mfaSubject: MfaSubjectPort, encryptionService: MfaEncryptionService, channels: IMfaChannel[]);
+    /**
+     * Initializes setup for a specific MFA method.
+     */
+    initSetup(userId: string, method: string, context?: IMfaSetupContext): Promise<IMfaSetup>;
+    /**
+     * Verifies the initial code for a method and issues backup codes.
+     */
+    verifySetup(userId: string, method: string, code: string): Promise<IMfaConfirmation>;
+    /**
+     * Verifies a login challenge using the selected method or backup code.
+     */
+    verifyChallenge(userId: string, method: string, code: string): Promise<boolean>;
+    /**
+     * Returns enabled methods and preferred method for a user.
+     */
+    getEnabledMethods(userId: string): Promise<{
+        methods: string[];
+        preferredMethod?: string;
+    }>;
+    /**
+     * Issues out-of-band challenge codes for login flows for applicable channels.
+     */
+    issueChallenges(userId: string, methods: ReadonlyArray<string>): Promise<void>;
+    /**
+     * Updates the preferred MFA method.
+     */
+    setPreferredMethod(userId: string, method: string): Promise<void>;
+    /**
+     * Regenerates backup codes.
+     */
+    regenerateBackupCodes(userId: string): Promise<ReadonlyArray<string>>;
+    /**
+     * Disables MFA for a user and clears channel secrets.
+     */
+    disable(userId: string): Promise<void>;
+    get registeredMethods(): string[];
+    private requireChannel;
+    private generateBackupCodes;
+    private tryConsumeBackupCode;
+    private getUser;
+    private touchVerification;
+}