@oneuptime/common 12.0.21 → 12.0.22

package/Server/Services/UserService.ts

@@ -45,6 +45,7 @@ import ProductAnalytics from "../Utils/ProductAnalytics";
 import MarketingEventUtil from "../Utils/Marketing/MarketingEventUtil";
 import { MarketingEventType } from "../../Types/Marketing/MarketingEvent";
 import UserTotpAuthService from "./UserTotpAuthService";
+import UserTwoFactorBackupCodeService from "./UserTwoFactorBackupCodeService";
 import UserWebAuthnService from "./UserWebAuthnService";
 import BadDataException from "../../Types/Exception/BadDataException";
 import NotFoundException from "../../Types/Exception/NotFoundException";
@@ -819,6 +820,18 @@ export class Service extends DatabaseService<Model> {
     const verifiedTwoFactorAuthMethodCount: number =
       await this.countVerifiedTwoFactorAuthMethods(userId);
 
+    /*
+     * Read separately from the method count above, and NOT added to it. See
+     * the note on `deriveTwoFactorAuthStatus`: folding recovery codes into the
+     * configured-method count would report an account whose authenticator is
+     * gone as fully set up, and login would keep sending it to the challenge
+     * screen until the last code was spent.
+     */
+    const unusedTwoFactorBackupCodeCount: number =
+      await UserTwoFactorBackupCodeService.countUnusedForUser({
+        userId: userId,
+      });
+
     return {
       hasPassword: Boolean(user.password),
       isEmailVerified: Boolean(user.isEmailVerified),
@@ -828,6 +841,7 @@ export class Service extends DatabaseService<Model> {
         verifiedMethodCount: verifiedTwoFactorAuthMethodCount,
       }),
       verifiedTwoFactorAuthMethodCount: verifiedTwoFactorAuthMethodCount,
+      unusedTwoFactorBackupCodeCount: unusedTwoFactorBackupCodeCount,
       hasPendingPasswordResetLink: hasPendingPasswordResetLink,
     };
   }
@@ -845,6 +859,17 @@ export class Service extends DatabaseService<Model> {
    * Counting unverified rows would therefore report a user who has never once
    * typed a code as fully configured -- and that user is precisely the one an
    * operator is looking at the page to help.
+   *
+   * BACKUP CODES ARE NOT COUNTED HERE, for a related reason one step further
+   * on. This number decides `deriveTwoFactorAuthStatus`, which decides whether
+   * login shows the two factor CHALLENGE or sends the account through
+   * enrolment. An account whose only remaining material was recovery codes
+   * would, if they counted, be shown a challenge it cannot answer except by
+   * spending a code -- one per sign-in, with no way to enrol a new
+   * authenticator, until the last one is gone. Recovery codes are the way back
+   * in to an account with a factor it cannot reach; they are not a factor.
+   * `UserAuthenticationStatus.unusedTwoFactorBackupCodeCount` reports them
+   * separately.
    */
   @CaptureSpan()
   private async countVerifiedTwoFactorAuthMethods(
@@ -1036,6 +1061,23 @@ export class Service extends DatabaseService<Model> {
       },
     });
 
+    /*
+     * The recovery codes go with the authenticators, and this is not
+     * bookkeeping. A backup code signs somebody in on its own, so a reset that
+     * cleared the TOTP secret but left a printed list of codes alive would
+     * have revoked nothing that an attacker who took the phone -- and the
+     * paper next to it -- still holds. "Reset two factor auth" has to mean all
+     * of the second-factor material, not the part that is easiest to see.
+     *
+     * It also matters in the harmless direction: the user is about to be sent
+     * through enrolment at their next sign-in, and codes minted against an
+     * authenticator that no longer exists are dead weight nobody would think
+     * to clear.
+     */
+    await UserTwoFactorBackupCodeService.deleteAllForUser({
+      userId: user.id!,
+    });
+
     /*
      * Ordered after the deletes, not before. A session that survives a reset
      * is a session that never has to prove the second factor again, which

package/Server/Services/UserTwoFactorBackupCodeService.ts

@@ -0,0 +1,355 @@
+import DatabaseService from "./DatabaseService";
+import Model from "../../Models/DatabaseModels/UserTwoFactorBackupCode";
+import TwoFactorBackupCode, {
+  BackupCodeSetSize,
+} from "../Utils/TwoFactorBackupCode";
+import CreateBy from "../Types/Database/CreateBy";
+import { OnCreate } from "../Types/Database/Hooks";
+import QueryHelper from "../Types/Database/QueryHelper";
+import BadDataException from "../../Types/Exception/BadDataException";
+import LIMIT_MAX from "../../Types/Database/LimitMax";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
+import ObjectID from "../../Types/ObjectID";
+import PositiveNumber from "../../Types/PositiveNumber";
+import OneUptimeDate from "../../Types/Date";
+import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import logger from "../Utils/Logger";
+
+/**
+ * How many of a user's backup codes are left, for the profile page and the
+ * admin's account view.
+ *
+ * `total` and `unused` are both reported rather than just the remaining count
+ * because they answer different questions: "have you set backup codes up at
+ * all" and "how many can you still use". A user with ten codes and a user who
+ * has spent all ten both have a `total` of ten, and only the second needs to
+ * be told to regenerate.
+ */
+export interface TwoFactorBackupCodeStatus {
+  total: number;
+  unused: number;
+
+  /*
+   * When the current set was minted, or null if there are none. Read off the
+   * newest row rather than stored separately -- regeneration replaces the
+   * whole set in one call, so every row in a set shares a creation time to
+   * within a few milliseconds.
+   */
+  generatedAt: Date | null;
+}
+
+export class Service extends DatabaseService<Model> {
+  public constructor() {
+    super(Model);
+  }
+
+  /*
+   * The model denies create to everyone, so the only way a row is written is
+   * `regenerateForUser` below, as root. This hook is the second lock on the
+   * same door: it refuses any create that did not come through there.
+   *
+   * Worth having both because the two guards fail differently. The table
+   * permission is enforced by the CRUD API layer and is bypassed wholesale by
+   * `isRoot`, which every internal caller uses -- so a future service that
+   * reaches for `UserTwoFactorBackupCodeService.create()` with a plaintext
+   * code, or with no owner, would sail past it. What lands in `codeHash` is
+   * the credential; there is no recovering from writing the wrong thing there.
+   */
+  @CaptureSpan()
+  protected override async onBeforeCreate(
+    createBy: CreateBy<Model>,
+  ): Promise<OnCreate<Model>> {
+    if (!createBy.data.userId) {
+      throw new BadDataException("User id is required");
+    }
+
+    if (!createBy.data.codeHash) {
+      throw new BadDataException("Backup code hash is required");
+    }
+
+    /*
+     * A code that arrives already spent is a caller confusing itself about
+     * which end of the lifecycle it is at. Codes are minted usable and are
+     * spent only by `consumeCode`.
+     *
+     * Deleted rather than set to undefined: `exactOptionalPropertyTypes` is on,
+     * so the property being ABSENT and the property holding `undefined` are
+     * different things to the compiler, and only the first is allowed here.
+     */
+    delete createBy.data.usedAt;
+
+    return {
+      createBy: createBy,
+      carryForward: {},
+    };
+  }
+
+  /**
+   * Mint a fresh set of backup codes for one user, replacing whatever they
+   * had, and return the PLAINTEXT codes.
+   *
+   * This is the only moment the plaintext exists anywhere. The caller shows it
+   * to the user once and then it is gone -- only the keyed digests are stored,
+   * so nothing (not this service, not a master admin, not a database dump) can
+   * produce the codes again. That is the property the feature is worth having
+   * for, and it is why the API route wraps this in a response the UI is
+   * expected to make the user acknowledge.
+   *
+   * REPLACING rather than adding is deliberate. "Generate more codes" would
+   * leave the codes from a list the user printed, lost and then regenerated
+   * over still working, which defeats the point of regenerating after a
+   * suspected compromise.
+   *
+   * ALL OR NOTHING, and this is the part that needs care. The old set is
+   * deleted first, then the new rows are written one at a time -- so a failure
+   * partway through the loop would otherwise leave the account holding a few
+   * rows that WERE written and that the caller, having thrown, never showed to
+   * anybody. `getStatusForUser` would then report "4 backup codes" to a user
+   * who has never seen one of them: codes that are unusable in practice and
+   * that hide the fact that they have no recovery route left. That is the
+   * worst state this feature can produce, because it looks exactly like the
+   * good one.
+   *
+   * So a failure is compensated: everything written for this user is removed,
+   * and the account ends with NO codes and an error on screen. "You have no
+   * backup codes" is a state the profile page already tells the user to fix;
+   * "you have four codes you have never seen" is not.
+   *
+   * The compensating delete is itself best-effort -- if it also fails there is
+   * nothing further to try -- but it turns a silent, permanent trap into two
+   * consecutive infrastructure failures.
+   */
+  @CaptureSpan()
+  public async regenerateForUser(data: {
+    userId: ObjectID;
+    count?: number | undefined;
+  }): Promise<Array<string>> {
+    const count: number = data.count || BackupCodeSetSize;
+
+    await this.deleteAllForUser({ userId: data.userId });
+
+    const codes: Array<string> = TwoFactorBackupCode.generateCodeSet(count);
+
+    try {
+      for (const code of codes) {
+        const backupCode: Model = new Model();
+        backupCode.userId = data.userId;
+        backupCode.codeHash = TwoFactorBackupCode.hashCode({
+          code: code,
+          userId: data.userId,
+        });
+
+        await this.create({
+          data: backupCode,
+          props: {
+            isRoot: true,
+          },
+        });
+      }
+    } catch (err) {
+      try {
+        await this.deleteAllForUser({ userId: data.userId });
+      } catch (cleanupError) {
+        /*
+         * Swallowed so the ORIGINAL failure is what the caller sees. The
+         * cleanup error is the less useful of the two -- it explains why the
+         * rollback did not happen, not why the write did not.
+         */
+        logger.error(cleanupError);
+      }
+
+      throw err;
+    }
+
+    return codes;
+  }
+
+  /**
+   * Spend one of this user's backup codes, if the submitted code is one of
+   * them and has not been used already.
+   *
+   * ONE STATEMENT, ON PURPOSE
+   *
+   * The obvious shape -- find the row, check `usedAt`, then update it -- has a
+   * window between the read and the write, and "single use" is the entire
+   * guarantee a backup code offers. Two sign-in attempts carrying the same
+   * code that arrive together would both read a null `usedAt` and both be let
+   * in, which is precisely the property an attacker who has watched somebody
+   * type a code off a printed list would exploit.
+   *
+   * `usedAt IS NULL` in the WHERE clause moves the decision inside Postgres,
+   * where the row lock settles it: the first statement to reach the row
+   * updates it, the second matches nothing. `RETURNING "_id"` is what turns
+   * that into an answer for the caller -- an UPDATE that matched no rows and
+   * an UPDATE that matched one are otherwise indistinguishable from here.
+   *
+   * Written as raw parameterized SQL rather than through the ORM because no
+   * write path on DatabaseService both takes a non-primary-key predicate and
+   * reports what it matched. Column and table names are literals in this file,
+   * never caller input, and all three values are bound parameters.
+   *
+   * `deletedAt IS NULL` is included because soft-deleted rows are still
+   * physically present; without it, a code from a set that regeneration
+   * replaced would still sign somebody in.
+   *
+   * @returns true when a code was spent, false when the code was wrong,
+   *          already used, or belongs to somebody else.
+   */
+  @CaptureSpan()
+  public async consumeCode(data: {
+    userId: ObjectID;
+    code: string;
+  }): Promise<boolean> {
+    const normalizedCode: string = TwoFactorBackupCode.normalizeCode(data.code);
+
+    /*
+     * Refused before the query rather than hashed and looked up. An empty
+     * submission cannot be anybody's code, and letting it through would mean
+     * one round trip per empty request on a route an attacker can call.
+     */
+    if (!normalizedCode) {
+      return false;
+    }
+
+    const codeHash: string = TwoFactorBackupCode.hashCode({
+      code: normalizedCode,
+      userId: data.userId,
+    });
+
+    const rows: Array<{ _id: string }> = await this.getRepository()
+      .manager.query(
+        `UPDATE "UserTwoFactorBackupCode"
+            SET "usedAt" = $1, "updatedAt" = CURRENT_TIMESTAMP
+          WHERE "userId" = $2
+            AND "codeHash" = $3
+            AND "usedAt" IS NULL
+            AND "deletedAt" IS NULL
+      RETURNING "_id"`,
+        [OneUptimeDate.getCurrentDate(), data.userId.toString(), codeHash],
+      )
+      /*
+       * For an UPDATE the postgres driver hands back `[rows, rowCount]` rather
+       * than a bare row array, so the rows have to be unwrapped. Written
+       * defensively: a driver that returns the bare array instead must read as
+       * "no code was spent", never as a silent success.
+       */
+      .then((result: unknown): Array<{ _id: string }> => {
+        if (!Array.isArray(result)) {
+          return [];
+        }
+
+        const first: unknown = result[0];
+
+        return Array.isArray(first) ? (first as Array<{ _id: string }>) : [];
+      });
+
+    return rows.length > 0;
+  }
+
+  /**
+   * How many codes this user has, and how many are still spendable.
+   *
+   * Counted rather than fetched: the rows carry a credential digest and there
+   * is no caller that needs them, so nothing is loaded that a stray log line
+   * could then print.
+   */
+  @CaptureSpan()
+  public async getStatusForUser(data: {
+    userId: ObjectID;
+  }): Promise<TwoFactorBackupCodeStatus> {
+    const total: PositiveNumber = await this.countBy({
+      query: {
+        userId: data.userId,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    if (total.toNumber() === 0) {
+      return {
+        total: 0,
+        unused: 0,
+        generatedAt: null,
+      };
+    }
+
+    const unused: number = await this.countUnusedForUser({
+      userId: data.userId,
+    });
+
+    const newest: Model | null = await this.findOneBy({
+      query: {
+        userId: data.userId,
+      },
+      select: {
+        createdAt: true,
+      },
+      sort: {
+        createdAt: SortOrder.Descending,
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return {
+      total: total.toNumber(),
+      unused: unused,
+      generatedAt: newest?.createdAt || null,
+    };
+  }
+
+  /**
+   * How many unused codes this user has left.
+   *
+   * Split out from `getStatusForUser` because the login path needs exactly
+   * this number and nothing else: it decides whether the two factor challenge
+   * screen offers "use a backup code" at all, and it is answered on every
+   * two-factor sign-in.
+   *
+   * `usedAt: QueryHelper.isNull()` rather than `usedAt: null`. A bare null
+   * predicate is dropped by TypeORM rather than compiled to `IS NULL`, so the
+   * count would silently include spent codes and the login page would offer a
+   * recovery route to a user with nothing left to recover with.
+   */
+  @CaptureSpan()
+  public async countUnusedForUser(data: { userId: ObjectID }): Promise<number> {
+    const unused: PositiveNumber = await this.countBy({
+      query: {
+        userId: data.userId,
+        usedAt: QueryHelper.isNull(),
+      },
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return unused.toNumber();
+  }
+
+  /**
+   * Drop every backup code this user has.
+   *
+   * Called by regeneration, and by UserService.resetTwoFactorAuth -- an
+   * operator resetting two factor auth for somebody who lost a device must
+   * take the recovery codes with it. Leaving them behind would mean the reset
+   * did not actually revoke the account's second-factor material, which is the
+   * one thing the operator pressed the button to do.
+   */
+  @CaptureSpan()
+  public async deleteAllForUser(data: { userId: ObjectID }): Promise<void> {
+    await this.deleteBy({
+      query: {
+        userId: data.userId,
+      },
+      limit: LIMIT_MAX,
+      skip: 0,
+      props: {
+        isRoot: true,
+      },
+    });
+  }
+}
+
+export default new Service();

package/Server/Utils/TwoFactorBackupCode.ts

@@ -0,0 +1,266 @@
+import { EncryptionSecret } from "../EnvironmentConfig";
+import ObjectID from "../../Types/ObjectID";
+import CaptureSpan from "./Telemetry/CaptureSpan";
+import crypto from "crypto";
+
+/*
+ * Single-use recovery codes for an account whose second factor is gone --
+ * the phone that held the authenticator app, or the security key that is now
+ * in a taxi somewhere.
+ *
+ * WHY THIS IS SERVER-ONLY
+ *
+ * Nothing in this file falls back to Math.random. Common/Utils/UUID does, on
+ * purpose, because it is bundled into the dashboard and has to keep producing
+ * well-formed ids in a browser with no Web Crypto -- which is exactly why
+ * ObjectID.generate() must never mint a code here. A backup code is a
+ * password-equivalent credential; if the platform cannot produce secure
+ * randomness, generation must throw rather than quietly emit something
+ * predictable. Common/Server/Utils/VerificationCode.ts makes the same call for
+ * the same reason.
+ *
+ * THE CODE SPACE
+ *
+ * Ten characters drawn uniformly from a 32 symbol alphabet is 2^50 codes, and
+ * a user holds ten of them at once -- so a blind guess lands with probability
+ * ~10/2^50, about one in 10^14. That is far beyond anything the rate limiter
+ * needs to defend, which matters because it settles the design question a TOTP
+ * code cannot settle: the six digit space is small enough that the limiter IS
+ * the control, whereas here the code itself is.
+ *
+ * THE HASH
+ *
+ * Codes are stored as HMAC-SHA256 keyed by the instance's EncryptionSecret,
+ * never in the clear, and the fast keyed-digest lane is the RIGHT one here
+ * rather than scrypt. scrypt exists to make guessing a low-entropy,
+ * human-chosen secret expensive; a code minted above has no low-entropy
+ * structure to guess, so the cost would buy nothing and would be paid on every
+ * verification. Keying with the EncryptionSecret is what a bare SHA-256 would
+ * miss: it lives in configuration rather than in Postgres, so a database dump
+ * on its own cannot be run through a dictionary of every possible code.
+ *
+ * The digest is deterministic given (userId, code), which is deliberate and is
+ * what makes single-use consumption a single conditional UPDATE rather than a
+ * read of every one of the user's rows followed by a comparison of each. A
+ * per-row salt would forfeit that for no gain -- see the note on domain
+ * separation below for the property it would have been bought for, which the
+ * userId already provides.
+ */
+
+/**
+ * Crockford's Base32 alphabet: the digits and the uppercase letters, minus
+ * I, L, O and U.
+ *
+ * These codes get read off a screen and typed back in months later, possibly
+ * from a piece of paper in a drawer, so the alphabet is chosen for the eye
+ * rather than for density. I/1, L/1 and O/0 are the pairs people transcribe
+ * wrongly; U is dropped by Crockford so that no code can spell an obscenity
+ * at a user who did nothing to deserve one.
+ *
+ * Exactly 32 symbols, so each character carries a clean five bits and the
+ * entropy arithmetic in the header comment is exact rather than approximate.
+ */
+export const BackupCodeAlphabet: string = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** Characters per code. Ten symbols over a 32 symbol alphabet is 2^50. */
+export const BackupCodeLength: number = 10;
+
+/**
+ * How many codes a user is issued at once.
+ *
+ * Ten is enough that losing a phone does not become an emergency after the
+ * second sign-in, and small enough that the printed list is one short block a
+ * person will actually keep.
+ */
+export const BackupCodeSetSize: number = 10;
+
+/** Characters per group in the displayed form, e.g. `AB3D5-9XZQ2`. */
+const DISPLAY_GROUP_LENGTH: number = 5;
+
+/*
+ * Prefixed into every digest so a stored hash is bound to the scheme that
+ * produced it. If the construction below ever has to change, old rows keep
+ * verifying under the version they were written with instead of silently
+ * failing to match and locking a user out of their own recovery codes.
+ */
+const HASH_SCHEME_VERSION: string = "v1";
+
+/*
+ * Characters a person plausibly types in place of a symbol that is not in the
+ * alphabet. Applied before the strip below, so `O` becomes `0` rather than
+ * being deleted -- deleting it would shorten the code and guarantee a
+ * mismatch, which is the confusing failure this map exists to avoid.
+ */
+const AMBIGUOUS_CHARACTER_MAP: Record<string, string> = {
+  I: "1",
+  L: "1",
+  O: "0",
+};
+
+export default class TwoFactorBackupCode {
+  /**
+   * One code, drawn uniformly from the alphabet above.
+   *
+   * `crypto.randomInt` per character rather than `randomBytes(n) % 32`. The
+   * modulo version happens to be uniform for this alphabet only because 32
+   * divides 256, and it stops being uniform the moment somebody edits the
+   * alphabet -- silently, with no test that would notice. `randomInt` rejects
+   * out-of-range draws internally for whatever bound it is given, so the
+   * uniformity does not depend on a coincidence nobody wrote down.
+   */
+  @CaptureSpan()
+  public static generateCode(): string {
+    let code: string = "";
+
+    for (let index: number = 0; index < BackupCodeLength; index++) {
+      code += BackupCodeAlphabet.charAt(
+        crypto.randomInt(0, BackupCodeAlphabet.length),
+      );
+    }
+
+    return code;
+  }
+
+  /**
+   * A full set of distinct codes.
+   *
+   * Duplicates are not a security problem -- at 2^50 the birthday odds across
+   * ten draws are around 4e-14 -- but a duplicate WOULD be a correctness
+   * problem downstream: two rows sharing a digest means consuming one leaves a
+   * second, identical, still-valid code behind, so a "single-use" code would
+   * work twice. Cheaper to rule out here than to reason about there.
+   */
+  @CaptureSpan()
+  public static generateCodeSet(
+    count: number = BackupCodeSetSize,
+  ): Array<string> {
+    const codes: Set<string> = new Set<string>();
+
+    while (codes.size < count) {
+      codes.add(TwoFactorBackupCode.generateCode());
+    }
+
+    return Array.from(codes);
+  }
+
+  /**
+   * The form shown to the user: one hyphen in the middle, for the same reason
+   * the alphabet drops ambiguous letters -- a ten character run is hard to
+   * read back without losing your place.
+   *
+   * Purely cosmetic. `normalizeCode` strips the hyphen straight back out, so
+   * a user may type the code with it, without it, or with the spaces their
+   * password manager pasted in.
+   */
+  @CaptureSpan()
+  public static formatForDisplay(code: string): string {
+    const groups: Array<string> = [];
+
+    for (
+      let index: number = 0;
+      index < code.length;
+      index += DISPLAY_GROUP_LENGTH
+    ) {
+      groups.push(code.substring(index, index + DISPLAY_GROUP_LENGTH));
+    }
+
+    return groups.join("-");
+  }
+
+  /**
+   * Reduce whatever the user typed to the canonical form the digest is
+   * computed over.
+   *
+   * Everything here is about not rejecting somebody who supplied exactly the
+   * right secret material: the display hyphen, the spaces a clipboard adds,
+   * lowercase from a phone keyboard, and the three transcription confusions
+   * the alphabet was chosen to make survivable. Anything still outside the
+   * alphabet after that is dropped rather than rejected -- this is a
+   * canonicaliser, not a validator; the digest comparison is what decides
+   * whether a code is real.
+   *
+   * @param rawCode - The code exactly as submitted.
+   * @returns The code reduced to alphabet symbols, uppercase.
+   */
+  @CaptureSpan()
+  public static normalizeCode(rawCode: string): string {
+    /*
+     * The code arrives straight off a JSON body, so it is only a string
+     * because the client chose to send one. A number or an object here must
+     * fail verification, not throw out of `.toUpperCase` and surface as a 500.
+     */
+    if (typeof rawCode !== "string" || !rawCode) {
+      return "";
+    }
+
+    let normalized: string = "";
+
+    for (const character of rawCode.toUpperCase()) {
+      const mapped: string = AMBIGUOUS_CHARACTER_MAP[character] || character;
+
+      if (BackupCodeAlphabet.includes(mapped)) {
+        normalized += mapped;
+      }
+    }
+
+    return normalized;
+  }
+
+  /**
+   * The digest stored for one of `userId`'s codes.
+   *
+   * Domain separated by the owning user, which is what stops one precomputed
+   * table from inverting every account's codes at once and stops two users who
+   * happen to be issued the same code from being visibly linked by a matching
+   * row. The user id is known at verification time -- the password has already
+   * been accepted by then -- so binding to it costs nothing.
+   *
+   * Both parts are LENGTH-PREFIXED into the message rather than merely
+   * concatenated, so no pair of (userId, code) values can be rearranged into
+   * the same byte string as another pair. Concatenation alone is a real
+   * ambiguity, not a theoretical one: without prefixes, ("ab", "cd") and
+   * ("abc", "d") hash identically.
+   */
+  @CaptureSpan()
+  public static hashCode(data: { code: string; userId: ObjectID }): string {
+    const message: string = [
+      HASH_SCHEME_VERSION,
+      data.userId.toString(),
+      TwoFactorBackupCode.normalizeCode(data.code),
+    ]
+      .map((part: string) => {
+        return `${part.length}:${part}`;
+      })
+      .join("");
+
+    return crypto
+      .createHmac("sha256", EncryptionSecret.toString())
+      .update(message)
+      .digest("hex");
+  }
+
+  /**
+   * Compare two digests without leaking, through timing, how many leading
+   * characters matched.
+   *
+   * The consume path compares digests in Postgres rather than here, so this is
+   * for callers that already hold both -- but it exists so that nobody writing
+   * one reaches for `===` and hands an attacker a way to recover a stored hash
+   * one character at a time.
+   *
+   * Lengths are compared first because `crypto.timingSafeEqual` THROWS on a
+   * length mismatch. Digests here are always 64 hex characters, so an early
+   * exit only happens on malformed input, where the length is not the secret.
+   */
+  @CaptureSpan()
+  public static isHashEqual(a: string, b: string): boolean {
+    if (!a || !b || a.length !== b.length) {
+      return false;
+    }
+
+    return crypto.timingSafeEqual(
+      Buffer.from(a, "utf8"),
+      Buffer.from(b, "utf8"),
+    );
+  }
+}