@oneuptime/common 12.0.12 → 12.0.14

package/Server/Utils/UserRegistrationToken.ts

@@ -0,0 +1,182 @@
+import { AccountsRoute } from "../../ServiceRoute";
+import Hostname from "../../Types/API/Hostname";
+import Protocol from "../../Types/API/Protocol";
+import Route from "../../Types/API/Route";
+import URL from "../../Types/API/URL";
+import OneUptimeDate from "../../Types/Date";
+import Email from "../../Types/Email";
+import ObjectID from "../../Types/ObjectID";
+import EmailVerificationToken from "../../Models/DatabaseModels/EmailVerificationToken";
+import DatabaseConfig from "../DatabaseConfig";
+import EmailVerificationTokenService from "../Services/EmailVerificationTokenService";
+import CaptureSpan from "./Telemetry/CaptureSpan";
+
+/*
+ * An invited user exists in the database before they have ever authenticated.
+ * TeamMemberService creates the row so the membership has something to point
+ * at, and that row carries no password until the person registers.
+ *
+ * /signup is what hands that unclaimed row over, so the hand-over has to be
+ * gated on something only the mailbox owner can hold. Knowing the address is
+ * not enough: addresses at a company are guessable by construction, which is
+ * exactly how GHSA-qg84-6hrg-mr5g turned a pending invitation into an account
+ * takeover -- the guard there was `if (alreadySavedUser.password)`, and an
+ * unclaimed row's password is null, which is falsy.
+ *
+ * This token is that gate. It is minted when the invitation is sent, travels
+ * only inside the invitation email, and is spent the first time it is used.
+ *
+ * It reuses EmailVerificationToken rather than adding a table of its own: the
+ * shape is identical (user, email, opaque token, expiry) and the semantics are
+ * the same claim -- "the holder of this controls this mailbox". Spending one is
+ * therefore also proof of address ownership, which is why the signup path marks
+ * the account verified on the way through.
+ */
+
+/*
+ * Invitations are read when the person gets round to them, not when they are
+ * sent, so these live longer than the 24 hours an email-verification link gets.
+ * Expiring in a week still bounds how long a leaked invite mail stays useful.
+ */
+export const REGISTRATION_TOKEN_EXPIRY_IN_DAYS: number = 7;
+
+export default class UserRegistrationToken {
+  /*
+   * Mint a token for `email` and return it. The caller is responsible for
+   * putting it somewhere only the mailbox owner will see -- which in practice
+   * means a link in an email addressed to that same mailbox, and nowhere else.
+   * It must never be written into an API response.
+   */
+  @CaptureSpan()
+  public static async generateRegistrationToken(data: {
+    userId: ObjectID;
+    email: Email;
+  }): Promise<ObjectID> {
+    const token: ObjectID = ObjectID.generate();
+
+    const emailVerificationToken: EmailVerificationToken =
+      new EmailVerificationToken();
+    emailVerificationToken.userId = data.userId;
+    emailVerificationToken.email = data.email;
+    emailVerificationToken.token = token;
+    emailVerificationToken.expires = OneUptimeDate.getSomeDaysAfter(
+      REGISTRATION_TOKEN_EXPIRY_IN_DAYS,
+    );
+
+    await EmailVerificationTokenService.create({
+      data: emailVerificationToken,
+      props: {
+        isRoot: true,
+      },
+    });
+
+    return token;
+  }
+
+  /*
+   * The /accounts/register link an invited person follows. The email is carried
+   * alongside the token only to prefill (and lock) the form field; the token is
+   * the part that authorizes anything.
+   */
+  @CaptureSpan()
+  public static async getRegistrationLink(data: {
+    email: Email;
+    token: ObjectID;
+  }): Promise<URL> {
+    const host: Hostname = await DatabaseConfig.getHost();
+    const httpProtocol: Protocol = await DatabaseConfig.getHttpProtocol();
+
+    return URL.fromString(
+      new URL(
+        httpProtocol,
+        host,
+        new Route(AccountsRoute.toString()),
+      ).toString(),
+    )
+      .addRoute("/register")
+      .addQueryParam("email", data.email.toString(), true)
+      .addQueryParam("token", data.token.toString(), true);
+  }
+
+  // Mint a token and build the link that carries it, in one step.
+  @CaptureSpan()
+  public static async generateRegistrationLink(data: {
+    userId: ObjectID;
+    email: Email;
+  }): Promise<URL> {
+    const token: ObjectID = await this.generateRegistrationToken({
+      userId: data.userId,
+      email: data.email,
+    });
+
+    return await this.getRegistrationLink({
+      email: data.email,
+      token: token,
+    });
+  }
+
+  /*
+   * Spend a token. Returns true only if it exists, was minted for this exact
+   * address, has not expired, and had not already been spent.
+   *
+   * The delete is what makes it single-use, and it is deliberately the last
+   * word: `deleteOneBy` reports how many rows it removed, so two requests
+   * racing on the same token produce exactly one winner (the loser deletes
+   * nothing and gets false back) rather than two callers who both read a live
+   * token and both proceed.
+   *
+   * Every failure returns the same `false`. The caller must not report which
+   * check failed -- "expired" and "no such token" would tell someone probing
+   * with guessed tokens which of them had ever been real.
+   */
+  @CaptureSpan()
+  public static async consumeRegistrationToken(data: {
+    token: ObjectID;
+    email: Email;
+  }): Promise<boolean> {
+    const savedToken: EmailVerificationToken | null =
+      await EmailVerificationTokenService.findOneBy({
+        query: {
+          token: data.token,
+        },
+        select: {
+          _id: true,
+          email: true,
+          expires: true,
+        },
+        props: {
+          isRoot: true,
+        },
+      });
+
+    if (!savedToken || !savedToken.email || !savedToken.expires) {
+      return false;
+    }
+
+    /*
+     * A token is bound to the address it was mailed to. Without this, a token
+     * from any invitation the attacker had legitimately received would claim
+     * any other unclaimed account. Email lowercases on construction, so the
+     * string comparison is already case-insensitive.
+     */
+    if (savedToken.email.toString() !== data.email.toString()) {
+      return false;
+    }
+
+    if (OneUptimeDate.hasExpired(savedToken.expires)) {
+      return false;
+    }
+
+    const deletedCount: number =
+      await EmailVerificationTokenService.deleteOneBy({
+        query: {
+          _id: savedToken._id!,
+        },
+        props: {
+          isRoot: true,
+        },
+      });
+
+    return deletedCount === 1;
+  }
+}

package/Server/Utils/VerificationCode.ts

@@ -0,0 +1,134 @@
+import { EncryptionSecret } from "../EnvironmentConfig";
+import ObjectID from "../../Types/ObjectID";
+import crypto from "crypto";
+
+/*
+ * The cryptography behind notification-channel ownership checks: the codes
+ * mailed/texted/read out to a user to prove they hold the address or number
+ * they just added.
+ *
+ * This is deliberately server-only. Common/Types/Text is bundled into the
+ * dashboard and therefore has to tolerate a runtime with no CSPRNG; a code
+ * minted here has no such excuse, so nothing in this file falls back to
+ * Math.random. If the platform cannot produce secure randomness, generation
+ * throws and the channel simply cannot be added.
+ *
+ * WHY THE STORED VALUE IS A DIGEST
+ *
+ * A six-digit code is only a secret for as long as it is in flight. Storing
+ * the plaintext puts a live account-takeover token in a database column, a
+ * backup, a replica and every log line that ever dumps the row - and the
+ * column sits on a table (UserEmail and friends) whose entire access-control
+ * design exists because reading somebody else's row IS the attack. Keeping a
+ * keyed digest means a database dump alone yields nothing: the attacker also
+ * needs the deployment's EncryptionSecret, and even holding both, recovering
+ * the code means re-running the HMAC over the code space per row, because...
+ *
+ * WHY THE ROW ID IS IN THE MESSAGE
+ *
+ * ...the digest is domain-separated by the row it belongs to. Without that,
+ * one HMAC table of all 10^6 codes inverts every row in the table at once,
+ * and two rows that happened to draw the same code would be visibly equal.
+ * With it, the same code on two rows produces two unrelated digests.
+ *
+ * A fast hash is right here, unlike a password: the input is a value the
+ * server minted at random, so there is nothing to guess offline that the
+ * attempt counter is not already bounding online. The scheme version prefix
+ * is there so a future change of construction can be told apart from this one
+ * rather than silently invalidating or, worse, colliding with it.
+ */
+
+const HASH_SCHEME_VERSION: string = "v1";
+
+/*
+ * Six digits, matching what the notification templates and the dashboard's
+ * code input already expect. The code space is small on purpose - it has to
+ * be readable off a phone screen - which is exactly why every control around
+ * it (expiry, attempt counter, lockout, rate limit) is load-bearing rather
+ * than defence in depth.
+ */
+export const VERIFICATION_CODE_LENGTH: number = 6;
+
+export default class VerificationCode {
+  /*
+   * A fresh code, drawn uniformly from the whole code space.
+   *
+   * crypto.randomInt does the rejection sampling itself, so there is no modulo
+   * bias here and no need to hand-roll one. Leading zeros are kept: "000123"
+   * is a perfectly good code, and dropping them would quietly shrink the
+   * space by 10%.
+   */
+  public static generate(length: number = VERIFICATION_CODE_LENGTH): string {
+    let code: string = "";
+
+    for (let i: number = 0; i < length; i++) {
+      code += crypto.randomInt(0, 10).toString();
+    }
+
+    return code;
+  }
+
+  /*
+   * The digest to store for `code` on the row identified by `channelId`.
+   *
+   * Both inputs are length-prefixed into the message rather than merely
+   * concatenated, so no pair of (id, code) values can be rearranged into the
+   * same byte string as another pair.
+   */
+  public static hashCode(data: { code: string; channelId: ObjectID }): string {
+    const message: string = [
+      HASH_SCHEME_VERSION,
+      data.channelId.toString(),
+      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
+   * bytes matched.
+   *
+   * `===` on strings short-circuits at the first differing character, and the
+   * attacker here controls the plaintext that produces one side of the
+   * comparison. That is a much weaker oracle than it is for a password check -
+   * they would be recovering a digest of a value that expires in minutes - but
+   * a constant-time compare costs nothing and removes the question.
+   *
+   * Lengths are compared first. Both digests are always 64 hex characters, so
+   * an early return only happens on malformed input, where the length is not
+   * the secret.
+   */
+  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"),
+    );
+  }
+
+  /*
+   * A digest that no code can ever produce, for burning the outstanding
+   * challenge.
+   *
+   * Used when a row is locked out or successfully verified. The column is NOT
+   * NULL, so "there is no live code" cannot be expressed as null; it is
+   * expressed as a digest drawn at random from a 256-bit space, which the
+   * 10^6 possible codes cannot hit. Rotating rather than leaving the old
+   * digest in place matters: it means a lockout is not merely a pause an
+   * attacker can wait out with the same target still valid behind it.
+   */
+  public static generateUnusableHash(): string {
+    return crypto.randomBytes(32).toString("hex");
+  }
+}