@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/features/two-factor/two-factor.controller.js

@@ -0,0 +1,174 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwoFactorController = void 0;
+const common_1 = require("@nestjs/common");
+const strict_validation_pipe_1 = require("../../common/strict-validation.pipe.js");
+const request_context_1 = require("../../common/request-context.js");
+const auth_decorators_1 = require("../../guards/auth.decorators.js");
+const users_service_1 = require("../users/users.service.js");
+const two_factor_dto_1 = require("./two-factor.dto");
+const two_factor_service_1 = require("./two-factor.service");
+const constants_1 = require("../../constants.js");
+const refresh_token_cookie_1 = require("../../common/refresh-token-cookie.js");
+/**
+ * Two-factor authentication (authenticator app + backup codes).
+ *
+ *   GET  /auth/2fa                 is it on? how many backup codes are left?
+ *   POST /auth/2fa/setup           start: get the secret and QR-code URL
+ *   POST /auth/2fa/enable          finish: first code -> backup codes
+ *   POST /auth/2fa/disable         turn off (needs a code)
+ *   POST /auth/2fa/backup-codes    new backup codes (needs a code)
+ *   POST /auth/2fa/verify          second step of sign-in
+ */
+let TwoFactorController = class TwoFactorController {
+    twoFactor;
+    users;
+    constructor(twoFactor, users) {
+        this.twoFactor = twoFactor;
+        this.users = users;
+    }
+    /**
+     * GET /auth/2fa — Is 2FA on for the signed-in user, and how many backup codes are left?
+     *
+     * @param userId - From the access token.
+     * @returns `{ isEnabled, remainingBackupCodes }`.
+     */
+    async getStatus(userId) {
+        const user = await this.users.getUserOrThrow(userId);
+        return {
+            success: true,
+            isEnabled: user.isTwoFactorEnabled,
+            remainingBackupCodes: user.isTwoFactorEnabled ? await this.twoFactor.countRemainingBackupCodes(userId) : 0,
+        };
+    }
+    /**
+     * POST /auth/2fa/setup — Starts setup and returns the secret and QR-code URL.
+     *
+     * @param userId - From the access token.
+     * @returns See `TwoFactorService.startSetup`.
+     */
+    startSetup(userId) {
+        return this.twoFactor.startSetup(userId);
+    }
+    /**
+     * POST /auth/2fa/enable — Confirms setup with the first code and returns backup codes.
+     *
+     * @param user - The access token's claims (user id and session id).
+     * @param body - `{ code }`.
+     * @param request - Who is asking.
+     * @returns See `TwoFactorService.confirmSetup`.
+     */
+    enable(user, body, request) {
+        return this.twoFactor.confirmSetup(user.sub, user.sid, body.code, request);
+    }
+    /**
+     * POST /auth/2fa/disable — Turns 2FA off.
+     *
+     * @param userId - From the access token.
+     * @param body - `{ code }`: an authenticator or backup code.
+     * @param request - Who is asking.
+     * @returns `{ success: true }`.
+     */
+    disable(userId, body, request) {
+        return this.twoFactor.disable(userId, body.code, request);
+    }
+    /**
+     * POST /auth/2fa/backup-codes — Replaces all backup codes.
+     *
+     * @param userId - From the access token.
+     * @param body - `{ code }`: an authenticator or backup code.
+     * @returns The new backup codes.
+     */
+    regenerateBackupCodes(userId, body) {
+        return this.twoFactor.regenerateBackupCodes(userId, body.code);
+    }
+    /**
+     * POST /auth/2fa/verify — The second step of sign-in. Public: the caller has no tokens yet.
+     *
+     * @param body - `{ challengeToken, code }`.
+     * @param request - Who is asking.
+     * @returns Access and refresh tokens.
+     */
+    verify(body, request) {
+        return this.twoFactor.verifySignInChallenge(body.challengeToken, body.code, request);
+    }
+};
+exports.TwoFactorController = TwoFactorController;
+__decorate([
+    (0, common_1.Get)(),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], TwoFactorController.prototype, "getStatus", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.twoFactor.setup),
+    (0, auth_decorators_1.CheckSession)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", void 0)
+], TwoFactorController.prototype, "startSetup", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.twoFactor.enable),
+    (0, auth_decorators_1.CheckSession)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, auth_decorators_1.CurrentUser)()),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, two_factor_dto_1.TwoFactorCodeInput, Object]),
+    __metadata("design:returntype", void 0)
+], TwoFactorController.prototype, "enable", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.twoFactor.disable),
+    (0, auth_decorators_1.CheckSession)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __param(1, (0, common_1.Body)()),
+    __param(2, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, two_factor_dto_1.TwoFactorCodeInput, Object]),
+    __metadata("design:returntype", void 0)
+], TwoFactorController.prototype, "disable", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.twoFactor.backupCodes),
+    (0, auth_decorators_1.CheckSession)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, auth_decorators_1.CurrentUserId)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, two_factor_dto_1.TwoFactorCodeInput]),
+    __metadata("design:returntype", void 0)
+], TwoFactorController.prototype, "regenerateBackupCodes", null);
+__decorate([
+    (0, common_1.Post)(constants_1.ROUTES.twoFactor.verify),
+    (0, auth_decorators_1.Public)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Body)()),
+    __param(1, (0, request_context_1.CurrentRequest)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [two_factor_dto_1.VerifyTwoFactorChallengeInput, Object]),
+    __metadata("design:returntype", void 0)
+], TwoFactorController.prototype, "verify", null);
+exports.TwoFactorController = TwoFactorController = __decorate([
+    (0, common_1.Controller)(constants_1.ROUTES.twoFactor.prefix),
+    (0, refresh_token_cookie_1.LibraryController)(),
+    (0, common_1.UsePipes)(strict_validation_pipe_1.strictValidationPipe),
+    __metadata("design:paramtypes", [two_factor_service_1.TwoFactorService,
+        users_service_1.UsersService])
+], TwoFactorController);
+//# sourceMappingURL=two-factor.controller.js.map

package/dist/features/two-factor/two-factor.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-factor.controller.js","sourceRoot":"","sources":["../../../src/features/two-factor/two-factor.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA6F;AAC7F,4EAAuE;AACvE,8DAA0E;AAC1E,8DAA4F;AAE5F,kEAA8D;AAC9D,qDAAqF;AACrF,6DAAwD;AACxD,2CAAqC;AACrC,wEAAkE;AAElE;;;;;;;;;GASG;AAII,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAEX;IACA;IAFnB,YACmB,SAA2B,EAC3B,KAAmB;QADnB,cAAS,GAAT,SAAS,CAAkB;QAC3B,UAAK,GAAL,KAAK,CAAc;IACnC,CAAC;IAEJ;;;;;OAKG;IAEG,AAAN,KAAK,CAAC,SAAS,CAAkB,MAAc;QAC7C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACrD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,IAAI,CAAC,kBAAkB;YAClC,oBAAoB,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3G,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IAIH,UAAU,CAAkB,MAAc;QACxC,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;OAOG;IAIH,MAAM,CAAgB,IAAuB,EAAU,IAAwB,EAAoB,OAAuB;QACxH,OAAO,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;OAOG;IAIH,OAAO,CAAkB,MAAc,EAAU,IAAwB,EAAoB,OAAuB;QAClH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IAIH,qBAAqB,CAAkB,MAAc,EAAU,IAAwB;QACrF,OAAO,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;OAMG;IAIH,MAAM,CAAS,IAAmC,EAAoB,OAAuB;QAC3F,OAAO,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvF,CAAC;CACF,CAAA;AA5FY,kDAAmB;AAaxB;IADL,IAAA,YAAG,GAAE;IACW,WAAA,IAAA,+BAAa,GAAE,CAAA;;;;oDAO/B;AAWD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,SAAS,CAAC,KAAK,CAAC;IAC5B,IAAA,8BAAY,GAAE;IACd,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IACZ,WAAA,IAAA,+BAAa,GAAE,CAAA;;;;qDAE1B;AAaD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,SAAS,CAAC,MAAM,CAAC;IAC7B,IAAA,8BAAY,GAAE;IACd,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IAChB,WAAA,IAAA,6BAAW,GAAE,CAAA;IAA2B,WAAA,IAAA,aAAI,GAAE,CAAA;IAA4B,WAAA,IAAA,gCAAc,GAAE,CAAA;;6CAArC,mCAAkB;;iDAE9E;AAaD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,SAAS,CAAC,OAAO,CAAC;IAC9B,IAAA,8BAAY,GAAE;IACd,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IACf,WAAA,IAAA,+BAAa,GAAE,CAAA;IAAkB,WAAA,IAAA,aAAI,GAAE,CAAA;IAA4B,WAAA,IAAA,gCAAc,GAAE,CAAA;;6CAArC,mCAAkB;;kDAExE;AAYD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,SAAS,CAAC,WAAW,CAAC;IAClC,IAAA,8BAAY,GAAE;IACd,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IACD,WAAA,IAAA,+BAAa,GAAE,CAAA;IAAkB,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAO,mCAAkB;;gEAEtF;AAYD;IAHC,IAAA,aAAI,EAAC,kBAAM,CAAC,SAAS,CAAC,MAAM,CAAC;IAC7B,IAAA,wBAAM,GAAE;IACR,IAAA,iBAAQ,EAAC,mBAAU,CAAC,EAAE,CAAC;IAChB,WAAA,IAAA,aAAI,GAAE,CAAA;IAAuC,WAAA,IAAA,gCAAc,GAAE,CAAA;;qCAAhD,8CAA6B;;iDAEjD;8BA3FU,mBAAmB;IAH/B,IAAA,mBAAU,EAAC,kBAAM,CAAC,SAAS,CAAC,MAAM,CAAC;IACnC,IAAA,wCAAiB,GAAE;IACnB,IAAA,iBAAQ,EAAC,6CAAoB,CAAC;qCAGC,qCAAgB;QACpB,4BAAY;GAH3B,mBAAmB,CA4F/B"}

package/dist/features/two-factor/two-factor.dto.d.ts

@@ -0,0 +1,10 @@
+/** POST /auth/2fa/enable, /auth/2fa/disable, /auth/2fa/backup-codes */
+export declare class TwoFactorCodeInput {
+    /** The 6-digit code from the authenticator app, or a backup code such as "k7m2-x9p4". */
+    code: string;
+}
+/** POST /auth/2fa/verify (second step of sign-in) */
+export declare class VerifyTwoFactorChallengeInput extends TwoFactorCodeInput {
+    /** The challengeToken from the sign-in response. */
+    challengeToken: string;
+}

package/dist/features/two-factor/two-factor.dto.js

@@ -0,0 +1,37 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyTwoFactorChallengeInput = exports.TwoFactorCodeInput = void 0;
+const class_validator_1 = require("class-validator");
+const constants_1 = require("../../constants.js");
+/** POST /auth/2fa/enable, /auth/2fa/disable, /auth/2fa/backup-codes */
+class TwoFactorCodeInput {
+    /** The 6-digit code from the authenticator app, or a backup code such as "k7m2-x9p4". */
+    code;
+}
+exports.TwoFactorCodeInput = TwoFactorCodeInput;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(constants_1.CODE_INPUT_MAX_LENGTH),
+    __metadata("design:type", String)
+], TwoFactorCodeInput.prototype, "code", void 0);
+/** POST /auth/2fa/verify (second step of sign-in) */
+class VerifyTwoFactorChallengeInput extends TwoFactorCodeInput {
+    /** The challengeToken from the sign-in response. */
+    challengeToken;
+}
+exports.VerifyTwoFactorChallengeInput = VerifyTwoFactorChallengeInput;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(constants_1.RANDOM_TOKEN_INPUT_MAX_LENGTH),
+    __metadata("design:type", String)
+], VerifyTwoFactorChallengeInput.prototype, "challengeToken", void 0);
+//# sourceMappingURL=two-factor.dto.js.map

package/dist/features/two-factor/two-factor.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-factor.dto.js","sourceRoot":"","sources":["../../../src/features/two-factor/two-factor.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDAAsD;AACtD,2CAAmF;AAEnF,uEAAuE;AACvE,MAAa,kBAAkB;IAC7B,yFAAyF;IAEzF,IAAI,CAAS;CACd;AAJD,gDAIC;AADC;IADC,IAAA,0BAAQ,GAAE;IAAE,IAAA,2BAAS,EAAC,iCAAqB,CAAC;;gDAChC;AAGf,qDAAqD;AACrD,MAAa,6BAA8B,SAAQ,kBAAkB;IACnE,oDAAoD;IAEpD,cAAc,CAAS;CACxB;AAJD,sEAIC;AADC;IADC,IAAA,0BAAQ,GAAE;IAAE,IAAA,2BAAS,EAAC,yCAA6B,CAAC;;qEAC9B"}

package/dist/features/two-factor/two-factor.service.d.ts

@@ -0,0 +1,171 @@
+import { AuthOptions } from '../../auth-options.js';
+import { EncryptionService } from '../../common/encryption.service.js';
+import { RateLimiterService } from '../../common/rate-limiter.service.js';
+import { RequestContext } from '../../common/request-context.js';
+import { AuthEventsService } from '../events/auth-events.service.js';
+import { SessionService } from '../sessions/session.service.js';
+import { SettingsService } from '../settings/settings.service.js';
+import { SignInChallengesService } from '../sign-in/sign-in-challenges.service.js';
+import { SignInService } from '../sign-in/sign-in.service.js';
+import { SignedInResult } from '../sign-in/sign-in.types.js';
+import { UsersService } from '../users/users.service.js';
+/**
+ * Two-factor authentication with an authenticator app (Google Authenticator, Microsoft
+ * Authenticator, 1Password, Authy...), plus single-use backup codes for a lost phone.
+ *
+ * Turning it on:   POST /auth/2fa/setup   -> secret + QR-code URL
+ *                  POST /auth/2fa/enable  -> first code from the app; returns backup codes (shown once)
+ * Signing in:      sign-in returns { status: "two_factor_required", challengeToken }
+ *                  POST /auth/2fa/verify  -> challengeToken + code (or a backup code) -> tokens
+ */
+export declare class TwoFactorService {
+    private readonly options;
+    private readonly settingsService;
+    private readonly encryption;
+    private readonly users;
+    private readonly sessions;
+    private readonly signIn;
+    private readonly challenges;
+    private readonly rateLimiter;
+    private readonly events;
+    private readonly database;
+    constructor(options: AuthOptions, settingsService: SettingsService, encryption: EncryptionService, users: UsersService, sessions: SessionService, signIn: SignInService, challenges: SignInChallengesService, rateLimiter: RateLimiterService, events: AuthEventsService);
+    /**
+     * Starts setup: creates a new secret. Show `authenticatorAppUrl` as a QR code (and `secret` for
+     * typing by hand). Nothing changes for the user until they confirm with a code (`confirmSetup`).
+     * Calling it again replaces the unconfirmed secret.
+     *
+     * @param userId - The signed-in user.
+     * @returns The plain secret and the otpauth:// URL for the QR code.
+     * @throws AuthError FEATURE_DISABLED when 2FA is turned off in settings.
+     * @throws AuthError TWO_FACTOR_ALREADY_ENABLED when the user already has 2FA on.
+     */
+    startSetup(userId: string): Promise<{
+        success: true;
+        secret: string;
+        authenticatorAppUrl: string;
+    }>;
+    /**
+     * Finishes setup: the user types the first code from their app. Turns 2FA on, signs out other
+     * devices, and returns backup codes. Show them once and ask the user to save them.
+     *
+     * @param userId - The signed-in user.
+     * @param currentSessionId - This device's session, which stays signed in.
+     * @param code - The 6-digit code from the authenticator app.
+     * @param request - Who is asking (for the audit log).
+     * @returns The plain backup codes, formatted like "k7m2-x9p4".
+     * @throws AuthError TWO_FACTOR_SETUP_NOT_STARTED when `startSetup` wasn't called first.
+     * @throws AuthError INVALID_OTP when the code is wrong.
+     * @throws AuthError TOO_MANY_REQUESTS after too many attempts.
+     */
+    confirmSetup(userId: string, currentSessionId: string, code: unknown, request: RequestContext): Promise<{
+        success: true;
+        backupCodes: string[];
+    }>;
+    /**
+     * Turns 2FA off. Requires a current authenticator code or a backup code.
+     *
+     * @param userId - The signed-in user.
+     * @param code - An authenticator code or a backup code.
+     * @param request - Who is asking (for the audit log).
+     * @returns `{ success: true }`.
+     * @throws AuthError TWO_FACTOR_NOT_ENABLED when 2FA is already off.
+     * @throws AuthError INVALID_OTP when the code is wrong.
+     */
+    disable(userId: string, code: unknown, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * Replaces all backup codes (e.g. the user lost the list). The old codes stop working.
+     *
+     * @param userId - The signed-in user.
+     * @param code - An authenticator code or a backup code.
+     * @returns The new plain backup codes.
+     * @throws AuthError TWO_FACTOR_NOT_ENABLED when 2FA is off.
+     * @throws AuthError INVALID_OTP when the code is wrong.
+     */
+    regenerateBackupCodes(userId: string, code: unknown): Promise<{
+        success: true;
+        backupCodes: string[];
+    }>;
+    /**
+     * Counts the unused backup codes (show a warning when it gets low).
+     *
+     * @param userId - The user to check.
+     * @returns How many backup codes are left.
+     */
+    countRemainingBackupCodes(userId: string): Promise<number>;
+    /**
+     * Admin: turns 2FA off for a user who lost their phone and backup codes.
+     * Only call this after checking who the user is some other way.
+     *
+     * @param userId - The user whose 2FA is removed.
+     * @param adminUserId - The admin doing it (recorded in the audit log).
+     * @param request - Who is asking (for the audit log).
+     * @returns `{ success: true }`.
+     * @throws AuthError NOT_FOUND when the user doesn't exist.
+     */
+    resetForUser(userId: string, adminUserId: string, request: RequestContext): Promise<{
+        success: true;
+    }>;
+    /**
+     * The second step of sign-in: checks the code for a challenge token returned by the first step.
+     *
+     * @param challengeToken - The "ch_..." token from `{ status: "two_factor_required" }`.
+     * @param code - An authenticator code or a backup code.
+     * @param request - Who is asking (for rate limits, sessions and the audit log).
+     * @returns The signed-in result with access and refresh tokens.
+     * @throws AuthError INVALID_TOKEN when the challenge is unknown, used, expired or burnt by wrong codes.
+     * @throws AuthError INVALID_OTP when the code is wrong.
+     */
+    verifySignInChallenge(challengeToken: unknown, code: unknown, request: RequestContext): Promise<SignedInResult>;
+    /**
+     * @throws AuthError FEATURE_DISABLED when 2FA is turned off in settings.
+     */
+    private assertTwoFactorAllowed;
+    /**
+     * Accepts a 6-digit authenticator code, or a backup code (which is then used up).
+     *
+     * @param userId - The user the code belongs to.
+     * @param code - What the user typed.
+     * @returns True when the code was correct.
+     */
+    private checkAnyCode;
+    /**
+     * Checks an authenticator code and remembers its time step, so the same code can't be used twice.
+     * The UPDATE only succeeds if no newer code was accepted meanwhile (two requests at once).
+     *
+     * @param storedSecret - The user's row with the encrypted secret.
+     * @param code - What the user typed.
+     * @returns True when the code was correct and not used before.
+     */
+    private checkAuthenticatorCode;
+    /**
+     * Checks a backup code and marks it used, so it works only once.
+     *
+     * @param userId - The user the code belongs to.
+     * @param typedCode - What the user typed; dashes, spaces and capitals are ignored.
+     * @returns True when the code matched an unused backup code (and this request was the one to use it).
+     */
+    private useBackupCode;
+    /**
+     * Deletes old backup codes and creates new ones. Only their hashes are stored.
+     *
+     * @param userId - The user to create codes for.
+     * @returns The plain codes, formatted like "k7m2-x9p4", to show the user once.
+     */
+    private replaceBackupCodes;
+    /**
+     * Deletes the secret and backup codes and turns 2FA off, all in one transaction.
+     *
+     * @param userId - The user to turn 2FA off for.
+     */
+    private removeTwoFactor;
+    /**
+     * Binds the encrypted secret to its user, so a secret copied to another user's row won't decrypt.
+     *
+     * @param userId - The secret's owner.
+     * @returns The context for `EncryptionService`.
+     */
+    private encryptionContext;
+}