@oneuptime/common 12.0.21 → 12.0.22

package/build/dist/Models/DatabaseModels/UserTwoFactorBackupCode.js

@@ -0,0 +1,277 @@
+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);
+};
+import BaseModel from "./DatabaseBaseModel/DatabaseBaseModel";
+import User from "./User";
+import Route from "../../Types/API/Route";
+import AllowAccessIfSubscriptionIsUnpaid from "../../Types/Database/AccessControl/AllowAccessIfSubscriptionIsUnpaid";
+import ColumnAccessControl from "../../Types/Database/AccessControl/ColumnAccessControl";
+import TableAccessControl from "../../Types/Database/AccessControl/TableAccessControl";
+import AllowUserQueryWithoutTenant from "../../Types/Database/AllowUserQueryWithoutTenant";
+import ColumnLength from "../../Types/Database/ColumnLength";
+import ColumnType from "../../Types/Database/ColumnType";
+import CrudApiEndpoint from "../../Types/Database/CrudApiEndpoint";
+import CurrentUserCanAccessRecordBy from "../../Types/Database/CurrentUserCanAccessRecordBy";
+import EnableDocumentation from "../../Types/Database/EnableDocumentation";
+import TableColumn from "../../Types/Database/TableColumn";
+import TableColumnType from "../../Types/Database/TableColumnType";
+import TableMetadata from "../../Types/Database/TableMetadata";
+import IconProp from "../../Types/Icon/IconProp";
+import ObjectID from "../../Types/ObjectID";
+import Permission from "../../Types/Permission";
+import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm";
+/*
+ * One single-use recovery code, for the sign-in a user cannot otherwise
+ * complete: the authenticator app went down with the phone, or the security
+ * key is gone.
+ *
+ * ONE ROW PER CODE, NOT ONE ROW PER USER
+ *
+ * The alternative -- a single row holding a JSON array of digests -- would
+ * make consuming a code a read-modify-write of the whole array, and two
+ * sign-in attempts arriving together would each write back a copy of the array
+ * missing only their own code, so one of the two consumed codes would come
+ * back to life. A row per code turns consumption into one conditional UPDATE
+ * that Postgres settles for us (see UserTwoFactorBackupCodeService.consumeCode).
+ *
+ * IT IS NOT A SECOND FACTOR, AND IS DELIBERATELY NOT COUNTED AS ONE
+ *
+ * UserService.countVerifiedTwoFactorAuthMethods sums TOTP apps and security
+ * keys and does NOT look here. That is load-bearing rather than an oversight:
+ * an account whose only remaining "method" was a backup code would read as
+ * fully configured, so login would send it to the two factor CHALLENGE screen
+ * instead of through enrolment -- and the user, having no authenticator left
+ * to enrol from, would burn recovery codes one per sign-in until they ran out
+ * and then be locked out for good. Backup codes are the way BACK IN to an
+ * account that has a factor it cannot currently reach; they are not the
+ * factor.
+ *
+ * NOTHING HERE IS WRITABLE THROUGH THE CRUD API
+ *
+ * Every table permission except read is empty, so codes can only be minted by
+ * the service (which writes as root) -- never by a caller choosing their own.
+ * A user who could POST their own code has turned a stolen password into a
+ * permanent second factor of their own devising.
+ */
+let UserTwoFactorBackupCode = class UserTwoFactorBackupCode extends BaseModel {
+    constructor() {
+        super(...arguments);
+        /*
+         * HMAC-SHA256 of the code, keyed by the instance's EncryptionSecret and
+         * domain separated by the owning user -- see
+         * Common/Server/Utils/TwoFactorBackupCode.ts for the construction.
+         *
+         * Read is denied to EVERYONE, including the owner and a master admin. There
+         * is no product question this column answers: the plaintext is shown once,
+         * at generation, and never again. A master admin bypasses column read
+         * permissions on some paths, which is exactly why nothing here is worth
+         * shipping to a browser even in digest form.
+         *
+         * Not UNIQUE. The digest is domain separated by user, so two users cannot
+         * collide even if they were issued the same code, and within one user
+         * `generateCodeSet` already rules duplicates out -- a unique constraint
+         * would add nothing and would turn an astronomically unlikely collision
+         * into a failed regeneration for somebody who is already having a bad day.
+         */
+        this.codeHash = undefined;
+        /*
+         * When this code was spent, or null while it is still usable.
+         *
+         * The row is kept rather than deleted on use, for two reasons that both
+         * matter to somebody recovering an account: the profile page can say "3 of
+         * 10 remaining" instead of silently shrinking a list, and a user who is
+         * asking "did somebody else get into my account?" has a timestamp to look
+         * at rather than an absence.
+         */
+        this.usedAt = undefined;
+        this.deletedByUser = undefined;
+        this.deletedByUserId = undefined;
+        this.user = undefined;
+        this.userId = undefined;
+    }
+};
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [],
+        update: [],
+    }),
+    TableColumn({
+        type: TableColumnType.ShortText,
+        canReadOnRelationQuery: false,
+        title: "Backup Code Hash",
+        description: "Keyed hash of this single-use two factor backup code",
+        hideColumnInDocumentation: true,
+    }),
+    Column({
+        type: ColumnType.ShortText,
+        length: ColumnLength.ShortText,
+        nullable: false,
+        unique: false,
+    }),
+    __metadata("design:type", String)
+], UserTwoFactorBackupCode.prototype, "codeHash", void 0);
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [Permission.CurrentUser],
+        update: [],
+    }),
+    TableColumn({
+        type: TableColumnType.Date,
+        canReadOnRelationQuery: false,
+        title: "Used At",
+        description: "When this backup code was used to sign in. Null while the code is still unused.",
+    }),
+    Column({
+        type: ColumnType.Date,
+        nullable: true,
+        unique: false,
+    }),
+    __metadata("design:type", Date)
+], UserTwoFactorBackupCode.prototype, "usedAt", void 0);
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [],
+        update: [],
+    }),
+    TableColumn({
+        manyToOneRelationColumn: "deletedByUserId",
+        type: TableColumnType.Entity,
+        title: "Deleted by User",
+        modelType: User,
+        description: "Relation to User who deleted this object (if this object was deleted by a User)",
+    }),
+    ManyToOne(() => {
+        return User;
+    }, {
+        cascade: false,
+        eager: false,
+        nullable: true,
+        onDelete: "SET NULL",
+        orphanedRowAction: "nullify",
+    }),
+    JoinColumn({ name: "deletedByUserId" }),
+    __metadata("design:type", User)
+], UserTwoFactorBackupCode.prototype, "deletedByUser", void 0);
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [],
+        update: [],
+    }),
+    TableColumn({
+        type: TableColumnType.ObjectID,
+        title: "Deleted by User ID",
+        description: "User ID who deleted this object (if this object was deleted by a User)",
+    }),
+    Column({
+        type: ColumnType.ObjectID,
+        nullable: true,
+        transformer: ObjectID.getDatabaseTransformer(),
+    }),
+    __metadata("design:type", ObjectID)
+], UserTwoFactorBackupCode.prototype, "deletedByUserId", void 0);
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [Permission.CurrentUser],
+        update: [],
+    }),
+    TableColumn({
+        manyToOneRelationColumn: "userId",
+        type: TableColumnType.Entity,
+        title: "User",
+        modelType: User,
+        description: "Relation to User who owns this backup code",
+    }),
+    ManyToOne(() => {
+        return User;
+    }, {
+        cascade: false,
+        eager: false,
+        nullable: true,
+        onDelete: "CASCADE",
+        orphanedRowAction: "nullify",
+    }),
+    JoinColumn({ name: "userId" }),
+    __metadata("design:type", User)
+], UserTwoFactorBackupCode.prototype, "user", void 0);
+__decorate([
+    ColumnAccessControl({
+        create: [],
+        read: [Permission.CurrentUser],
+        update: [],
+    }),
+    TableColumn({
+        type: TableColumnType.ObjectID,
+        title: "User ID",
+        description: "User ID who owns this backup code",
+    }),
+    Column({
+        type: ColumnType.ObjectID,
+        nullable: true,
+        transformer: ObjectID.getDatabaseTransformer(),
+    }),
+    __metadata("design:type", ObjectID)
+], UserTwoFactorBackupCode.prototype, "userId", void 0);
+UserTwoFactorBackupCode = __decorate([
+    EnableDocumentation({
+        isMasterAdminApiDocs: true,
+    }),
+    AllowAccessIfSubscriptionIsUnpaid(),
+    TableAccessControl({
+        /*
+         * Minting is POST /user-two-factor-backup-code/generate, which regenerates
+         * the whole set at once. There is no meaningful "create one code" operation
+         * and, more to the point, no safe one: the code is the credential, so a
+         * caller supplying it is choosing their own recovery secret.
+         */
+        create: [],
+        /*
+         * Read is open to the owner so the profile page can count what is left. It
+         * exposes nothing: `codeHash` denies read to everybody, so a row read here
+         * carries only its id, its `usedAt` and its owner.
+         */
+        read: [Permission.CurrentUser],
+        /*
+         * Consumption is a server-side write on the login path and regeneration
+         * replaces the set wholesale. A user-driven update or delete could only
+         * make a code stop working, which is the same thing regeneration does more
+         * clearly, and would give an attacker holding a session a way to quietly
+         * strip the account's recovery options.
+         */
+        delete: [],
+        update: [],
+    }),
+    CrudApiEndpoint(new Route("/user-two-factor-backup-code")),
+    Entity({
+        name: "UserTwoFactorBackupCode",
+    }),
+    TableMetadata({
+        tableName: "UserTwoFactorBackupCode",
+        singularName: "Two Factor Backup Code",
+        pluralName: "Two Factor Backup Codes",
+        icon: IconProp.Key,
+        tableDescription: "Single-use backup codes that let a user sign in when their two factor authentication device is unavailable",
+    }),
+    AllowUserQueryWithoutTenant(true),
+    CurrentUserCanAccessRecordBy("userId")
+    /*
+     * The entire hot path is `WHERE "userId" = ... AND "codeHash" = ...` -- the
+     * conditional UPDATE that consumes a code during a sign-in somebody is locked
+     * out of. `userId` alone leads the index so the profile page's "how many are
+     * left" count uses it too.
+     */
+    ,
+    Index(["userId", "codeHash"])
+], UserTwoFactorBackupCode);
+export default UserTwoFactorBackupCode;
+//# sourceMappingURL=UserTwoFactorBackupCode.js.map

package/build/dist/Models/DatabaseModels/UserTwoFactorBackupCode.js.map

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

package/build/dist/Server/API/UserTwoFactorBackupCodeAPI.js

@@ -0,0 +1,201 @@
+import Route from "../../Types/API/Route";
+import URL from "../../Types/API/URL";
+import OneUptimeDate from "../../Types/Date";
+import EmailTemplateType from "../../Types/Email/EmailTemplateType";
+import { DashboardRoute } from "../../ServiceRoute";
+import DatabaseConfig from "../DatabaseConfig";
+import MailService from "../Services/MailService";
+import UserService from "../Services/UserService";
+import UserMiddleware from "../Middleware/UserAuthorization";
+import UserTwoFactorBackupCodeService from "../Services/UserTwoFactorBackupCodeService";
+import TwoFactorBackupCode from "../Utils/TwoFactorBackupCode";
+import BaseAPI from "./BaseAPI";
+import UserTwoFactorBackupCode from "../../Models/DatabaseModels/UserTwoFactorBackupCode";
+import NotAuthenticatedException from "../../Types/Exception/NotAuthenticatedException";
+import Response from "../Utils/Response";
+import logger from "../Utils/Logger";
+/**
+ * The two routes a signed-in user needs to manage their recovery codes.
+ *
+ * Both act on the CALLER's own codes and nobody else's. There is deliberately
+ * no `:userId` parameter anywhere here: the owner is read from the validated
+ * access token, so there is no id for a caller to substitute and no ownership
+ * check to get wrong. `UserMiddleware.getUserMiddleware` is what puts it
+ * there.
+ */
+export default class UserTwoFactorBackupCodeAPI extends BaseAPI {
+    constructor() {
+        var _a;
+        super(UserTwoFactorBackupCode, UserTwoFactorBackupCodeService);
+        const crudApiPath = ((_a = new this.entityType().getCrudApiPath()) === null || _a === void 0 ? void 0 : _a.toString()) || "";
+        /*
+         * Mint a fresh set and return the plaintext codes.
+         *
+         * THIS RESPONSE IS THE ONLY COPY. Nothing is stored but keyed digests, so
+         * if the user closes the tab the codes are gone -- not recoverable by
+         * them, by an operator, or by anybody with the database. The UI is
+         * expected to make that unmissable, and the count of a previous set is
+         * returned alongside so the page can say what was just invalidated.
+         *
+         * It is a POST because it is destructive: calling it throws away every
+         * code the user was previously holding. A GET that silently voided a
+         * printed list -- on a browser prefetch, say -- would be a lockout with no
+         * user action behind it.
+         *
+         * NOT gated on `enableTwoFactorAuth`. Generating codes before turning two
+         * factor auth on is the sensible order to do it in, and refusing here
+         * would push users into the exact sequence -- enable first, find recovery
+         * later -- that produces the lost-device support ticket this whole feature
+         * exists to prevent.
+         */
+        this.router.post(`${crudApiPath}/generate`, UserMiddleware.getUserMiddleware, async (req, res, next) => {
+            try {
+                const userId = UserTwoFactorBackupCodeAPI.getCurrentUserId(req);
+                const previousStatus = await UserTwoFactorBackupCodeService.getStatusForUser({
+                    userId: userId,
+                });
+                const codes = await UserTwoFactorBackupCodeService.regenerateForUser({
+                    userId: userId,
+                });
+                /*
+                 * The codes themselves are NEVER logged -- they are sign-in
+                 * credentials, and logger output reaches stdout, the recent-log
+                 * buffer and telemetry at once. The fact that a set was minted is
+                 * worth recording: it is how an operator later reconstructs "who
+                 * invalidated the codes this user says they had".
+                 */
+                logger.info(`Two factor backup codes regenerated for user: ${userId.toString()}`);
+                /*
+                 * Tell the account holder, at their address rather than in this
+                 * browser.
+                 *
+                 * This route is the destructive one and it is the one with the least
+                 * standing in front of it: a session alone -- no password, no second
+                 * factor -- silently voids every recovery code the user is holding.
+                 * Somebody who has stolen a session can therefore remove the owner's
+                 * way back in and leave no trace the owner would ever look at, and
+                 * the owner finds out at the next sign-in they cannot complete.
+                 *
+                 * The mail does not prevent that; it makes it visible, which is the
+                 * same bargain `sendTwoFactorBackupCodeUsedEmail` strikes on the
+                 * login path. Re-prompting for the password here would be stronger
+                 * still, and is the obvious next step -- it needs a re-authentication
+                 * mechanism this codebase does not have yet, so it is deliberately
+                 * not invented on this route alone.
+                 *
+                 * Detached and never awaited: an unreachable mail server must not
+                 * fail a regeneration that has already replaced the user's codes,
+                 * because the response carries the only copy of the new ones.
+                 */
+                UserTwoFactorBackupCodeAPI.notifyCodesRegenerated({
+                    userId: userId,
+                    newCodeCount: codes.length,
+                }).catch((err) => {
+                    logger.error(err);
+                });
+                return Response.sendJsonObjectResponse(req, res, {
+                    /*
+                     * Hyphenated for the page to render as-is. The verify route
+                     * normalizes whatever comes back, so a user may type them with
+                     * the hyphen, without it, or with whatever spacing their password
+                     * manager pasted in.
+                     */
+                    codes: codes.map((code) => {
+                        return TwoFactorBackupCode.formatForDisplay(code);
+                    }),
+                    replacedCodeCount: previousStatus.total,
+                });
+            }
+            catch (err) {
+                return next(err);
+            }
+        });
+        /*
+         * How many codes the caller has left.
+         *
+         * Carries no code material of any kind -- three numbers and a date -- so
+         * it is safe for the profile page to poll and safe to render anywhere a
+         * session already exists.
+         */
+        this.router.get(`${crudApiPath}/status`, UserMiddleware.getUserMiddleware, async (req, res, next) => {
+            try {
+                const userId = UserTwoFactorBackupCodeAPI.getCurrentUserId(req);
+                const status = await UserTwoFactorBackupCodeService.getStatusForUser({
+                    userId: userId,
+                });
+                /*
+                 * A stale "you have 8 codes left" served out of a browser cache
+                 * after the user has just regenerated is a user who thinks the
+                 * button did nothing.
+                 */
+                Response.setNoCacheHeaders(res);
+                return Response.sendJsonObjectResponse(req, res, {
+                    total: status.total,
+                    unused: status.unused,
+                    generatedAt: status.generatedAt
+                        ? status.generatedAt.toISOString()
+                        : null,
+                });
+            }
+            catch (err) {
+                return next(err);
+            }
+        });
+    }
+    /**
+     * Mail the owner that their backup codes were replaced.
+     *
+     * Separate from the handler so the handler stays readable, and `private
+     * static` because nothing outside this route should be announcing a
+     * regeneration that did not happen here.
+     *
+     * Reads the address itself rather than taking it from the request: the only
+     * thing the caller proved is which user they are, and the address this goes
+     * to has to be the one on the account, not one they supplied.
+     */
+    static async notifyCodesRegenerated(data) {
+        const user = await UserService.findOneById({
+            id: data.userId,
+            select: {
+                email: true,
+            },
+            props: {
+                isRoot: true,
+            },
+        });
+        if (!user || !user.email) {
+            return;
+        }
+        const host = await DatabaseConfig.getHost();
+        const httpProtocol = await DatabaseConfig.getHttpProtocol();
+        await MailService.sendMail({
+            toEmail: user.email,
+            subject: "Your OneUptime two factor backup codes were replaced",
+            templateType: EmailTemplateType.TwoFactorBackupCodesRegenerated,
+            vars: {
+                generatedAt: OneUptimeDate.getCurrentDateAsFormattedString(),
+                newCodeCount: data.newCodeCount.toString(),
+                twoFactorAuthUrl: new URL(httpProtocol, host, new Route(DashboardRoute.toString()).addRoute("/user-profile/two-factor-auth")).toString(),
+                homeUrl: new URL(httpProtocol, host).toString(),
+            },
+        });
+    }
+    /**
+     * The signed-in caller, from the token the middleware validated.
+     *
+     * Throws rather than returning null: every route in this file acts on the
+     * caller's own credentials, so "no caller" is not a case any of them can
+     * meaningfully proceed with. The middleware ahead of them should already
+     * have refused, which makes this a second lock rather than the first.
+     */
+    static getCurrentUserId(req) {
+        var _a;
+        const userId = (_a = req
+            .userAuthorization) === null || _a === void 0 ? void 0 : _a.userId;
+        if (!userId) {
+            throw new NotAuthenticatedException("You are not authenticated. Please sign in.");
+        }
+        return userId;
+    }
+}
+//# sourceMappingURL=UserTwoFactorBackupCodeAPI.js.map

package/build/dist/Server/API/UserTwoFactorBackupCodeAPI.js.map

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

package/build/dist/Server/Infrastructure/Postgres/SchemaMigrations/1789100000000-AddUserTwoFactorBackupCode.js

@@ -0,0 +1,46 @@
+/*
+ * Single-use two factor backup codes, so losing an authenticator app or a
+ * security key stops being an account lockout that only a master admin can
+ * undo.
+ *
+ * One row per code rather than an array column on User: consuming a code is
+ * then one conditional UPDATE that Postgres serialises for us, instead of a
+ * read-modify-write of an array where two simultaneous sign-ins would each
+ * write back a copy missing only their own code.
+ *
+ * `codeHash` holds an HMAC-SHA256 keyed by the instance EncryptionSecret and
+ * domain separated by the owning user -- never a code in the clear. It is a
+ * plain varchar rather than a `hashed: true` column because the write path's
+ * hashing lanes do neither of those things: the salted lane is scrypt (right
+ * for a guessable password, pure cost for a 2^50 random code) and the unsalted
+ * lane is a bare SHA-256 with no per-user binding. See
+ * Common/Server/Utils/TwoFactorBackupCode.ts.
+ *
+ * The (userId, codeHash) index is the sign-in lookup, which happens while
+ * somebody is locked out and waiting. `usedAt` is deliberately not in it: a
+ * user holds ten rows, so Postgres filters those in memory for nothing.
+ */
+export class AddUserTwoFactorBackupCode1789100000000 {
+    constructor() {
+        this.name = "AddUserTwoFactorBackupCode1789100000000";
+    }
+    async up(queryRunner) {
+        await queryRunner.query(`CREATE TABLE "UserTwoFactorBackupCode" ("_id" uuid NOT NULL DEFAULT uuid_generate_v4(), "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "deletedAt" TIMESTAMP WITH TIME ZONE, "version" integer NOT NULL, "codeHash" character varying(100) NOT NULL, "usedAt" TIMESTAMP WITH TIME ZONE, "deletedByUserId" uuid, "userId" uuid, CONSTRAINT "PK_8007aa681bcad47b88b906319ed" PRIMARY KEY ("_id"))`);
+        await queryRunner.query(`CREATE INDEX "IDX_19a5937a4f6bd993383b31f3a2" ON "UserTwoFactorBackupCode" ("userId", "codeHash") `);
+        await queryRunner.query(`ALTER TABLE "UserTwoFactorBackupCode" ADD CONSTRAINT "FK_b6f9bfb29ab554076a2d8dde717" FOREIGN KEY ("deletedByUserId") REFERENCES "User"("_id") ON DELETE SET NULL ON UPDATE NO ACTION`);
+        /*
+         * CASCADE, not SET NULL. An orphaned row would be a live sign-in
+         * credential for an account that no longer exists -- and, with `userId`
+         * null, invisible to every query in the service, which all key on the
+         * owner.
+         */
+        await queryRunner.query(`ALTER TABLE "UserTwoFactorBackupCode" ADD CONSTRAINT "FK_dd1f93f94cd3a4f39435b56d944" FOREIGN KEY ("userId") REFERENCES "User"("_id") ON DELETE CASCADE ON UPDATE NO ACTION`);
+    }
+    async down(queryRunner) {
+        await queryRunner.query(`ALTER TABLE "UserTwoFactorBackupCode" DROP CONSTRAINT "FK_dd1f93f94cd3a4f39435b56d944"`);
+        await queryRunner.query(`ALTER TABLE "UserTwoFactorBackupCode" DROP CONSTRAINT "FK_b6f9bfb29ab554076a2d8dde717"`);
+        await queryRunner.query(`DROP INDEX "public"."IDX_19a5937a4f6bd993383b31f3a2"`);
+        await queryRunner.query(`DROP TABLE "UserTwoFactorBackupCode"`);
+    }
+}
+//# sourceMappingURL=1789100000000-AddUserTwoFactorBackupCode.js.map

package/build/dist/Server/Infrastructure/Postgres/SchemaMigrations/1789100000000-AddUserTwoFactorBackupCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"1789100000000-AddUserTwoFactorBackupCode.js","sourceRoot":"","sources":["../../../../../../Server/Infrastructure/Postgres/SchemaMigrations/1789100000000-AddUserTwoFactorBackupCode.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,uCAAuC;IAApD;QAGS,SAAI,GAAW,yCAAyC,CAAC;IAmClE,CAAC;IAjCQ,KAAK,CAAC,EAAE,CAAC,WAAwB;QACtC,MAAM,WAAW,CAAC,KAAK,CACrB,4cAA4c,CAC7c,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CACrB,oGAAoG,CACrG,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CACrB,uLAAuL,CACxL,CAAC;QACF;;;;;WAKG;QACH,MAAM,WAAW,CAAC,KAAK,CACrB,6KAA6K,CAC9K,CAAC;IACJ,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,WAAwB;QACxC,MAAM,WAAW,CAAC,KAAK,CACrB,wFAAwF,CACzF,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CACrB,wFAAwF,CACzF,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CACrB,sDAAsD,CACvD,CAAC;QACF,MAAM,WAAW,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAClE,CAAC;CACF"}

package/build/dist/Server/Infrastructure/Postgres/SchemaMigrations/Index.js

@@ -543,6 +543,7 @@ import { AddDetectionRuleIncidentColumns1788600000000 } from "./1788600000000-Ad
 import { RemoveMarketingConversionUploadState1788700000000 } from "./1788700000000-RemoveMarketingConversionUploadState";
 import { DropMarketingConversionAddEnterpriseLicenseEmail1788800000000 } from "./1788800000000-DropMarketingConversionAddEnterpriseLicenseEmail";
 import { AddUserSlackAndMicrosoftTeams1789000000000 } from "./1789000000000-AddUserSlackAndMicrosoftTeams";
+import { AddUserTwoFactorBackupCode1789100000000 } from "./1789100000000-AddUserTwoFactorBackupCode";
 import { MigrationName1787142779538 } from "./1787142779538-MigrationName";
 import { MigrationName1787156982416 } from "./1787156982416-MigrationName";
 export default [
@@ -1093,5 +1094,6 @@ export default [
     RemoveMarketingConversionUploadState1788700000000,
     DropMarketingConversionAddEnterpriseLicenseEmail1788800000000,
     AddUserSlackAndMicrosoftTeams1789000000000,
+    AddUserTwoFactorBackupCode1789100000000,
 ];
 //# sourceMappingURL=Index.js.map