@oneuptime/common 12.0.13 → 12.0.14

package/Tests/Server/Utils/UserRegistrationToken.test.ts

@@ -0,0 +1,322 @@
+import EmailVerificationToken from "../../../Models/DatabaseModels/EmailVerificationToken";
+import DatabaseConfig from "../../../Server/DatabaseConfig";
+import EmailVerificationTokenService from "../../../Server/Services/EmailVerificationTokenService";
+import UserRegistrationToken, {
+  REGISTRATION_TOKEN_EXPIRY_IN_DAYS,
+} from "../../../Server/Utils/UserRegistrationToken";
+import Hostname from "../../../Types/API/Hostname";
+import Protocol from "../../../Types/API/Protocol";
+import URL from "../../../Types/API/URL";
+import OneUptimeDate from "../../../Types/Date";
+import Email from "../../../Types/Email";
+import ObjectID from "../../../Types/ObjectID";
+import { afterEach, beforeEach, describe, expect, test } from "@jest/globals";
+
+/*
+ * The gate on claiming an invited account (GHSA-qg84-6hrg-mr5g).
+ *
+ * An invited user's row exists, with no password, before they have ever
+ * authenticated. Whoever can spend one of these tokens gets to put a password
+ * on that row and walk in, so the interesting cases here are all the ways a
+ * token must NOT be spendable: not by a different address, not after it has
+ * expired, and not twice.
+ */
+
+const USER_ID: ObjectID = new ObjectID("11111111-1111-4111-8111-111111111111");
+const TOKEN_ROW_ID: ObjectID = new ObjectID(
+  "22222222-2222-4222-8222-222222222222",
+);
+const TOKEN: ObjectID = new ObjectID("33333333-3333-4333-8333-333333333333");
+
+const INVITED_EMAIL: Email = new Email("alice@company.com");
+const OTHER_EMAIL: Email = new Email("mallory@company.com");
+
+let createSpy: jest.SpyInstance;
+let findOneBySpy: jest.SpyInstance;
+let deleteOneBySpy: jest.SpyInstance;
+
+/*
+ * A live, valid token row for INVITED_EMAIL.
+ *
+ * Overrides are loosely typed so a test can put a column back to undefined --
+ * a half-written row read out of the database. exactOptionalPropertyTypes
+ * forbids expressing that through Partial<EmailVerificationToken>, and those
+ * are exactly the rows consumeRegistrationToken has to refuse.
+ */
+function tokenRow(
+  overrides: Record<string, unknown> = {},
+): EmailVerificationToken {
+  const row: EmailVerificationToken = new EmailVerificationToken(TOKEN_ROW_ID);
+  row._id = TOKEN_ROW_ID.toString();
+  row.email = INVITED_EMAIL;
+  row.expires = OneUptimeDate.getSomeDaysAfter(1);
+
+  return Object.assign(row, overrides);
+}
+
+beforeEach(() => {
+  createSpy = jest
+    .spyOn(EmailVerificationTokenService, "create")
+    .mockResolvedValue(new EmailVerificationToken());
+
+  findOneBySpy = jest
+    .spyOn(EmailVerificationTokenService, "findOneBy")
+    .mockResolvedValue(tokenRow());
+
+  deleteOneBySpy = jest
+    .spyOn(EmailVerificationTokenService, "deleteOneBy")
+    .mockResolvedValue(1);
+
+  jest
+    .spyOn(DatabaseConfig, "getHost")
+    .mockResolvedValue(new Hostname("oneuptime.test"));
+  jest
+    .spyOn(DatabaseConfig, "getHttpProtocol")
+    .mockResolvedValue(Protocol.HTTPS);
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+describe("UserRegistrationToken.generateRegistrationToken", () => {
+  test("binds the token to the user and the address it will be mailed to", async () => {
+    const token: ObjectID =
+      await UserRegistrationToken.generateRegistrationToken({
+        userId: USER_ID,
+        email: INVITED_EMAIL,
+      });
+
+    const created: EmailVerificationToken = createSpy.mock.calls[0]![0][
+      "data"
+    ] as EmailVerificationToken;
+
+    expect(created.userId!.toString()).toBe(USER_ID.toString());
+    expect(created.email!.toString()).toBe(INVITED_EMAIL.toString());
+    expect(created.token!.toString()).toBe(token.toString());
+  });
+
+  test("mints a fresh unguessable token each time", async () => {
+    const first: ObjectID =
+      await UserRegistrationToken.generateRegistrationToken({
+        userId: USER_ID,
+        email: INVITED_EMAIL,
+      });
+    const second: ObjectID =
+      await UserRegistrationToken.generateRegistrationToken({
+        userId: USER_ID,
+        email: INVITED_EMAIL,
+      });
+
+    expect(first.toString()).not.toBe(second.toString());
+    expect(ObjectID.isValidUUID(first.toString())).toBe(true);
+  });
+
+  test("expires, and outlives a plain verification link", async () => {
+    /*
+     * Invitations get read when the person gets round to them, so these last
+     * days rather than the 24 hours a verification link gets. They still have
+     * to expire -- an invitation mail sitting in an old inbox forever is a
+     * standing key to the account.
+     */
+    await UserRegistrationToken.generateRegistrationToken({
+      userId: USER_ID,
+      email: INVITED_EMAIL,
+    });
+
+    const created: EmailVerificationToken = createSpy.mock.calls[0]![0][
+      "data"
+    ] as EmailVerificationToken;
+
+    /*
+     * The source stamps expires = now + N days, then a few milliseconds later
+     * this test reads the clock again to measure the gap. Measuring in whole
+     * days would truncate that sub-day drift down to N-1 (moment's diff rounds
+     * toward zero), which is a timing race that fails under CI load. Measure the
+     * raw gap in milliseconds and assert it lands in the (N-1, N]-day band: at
+     * most the configured N days, and strictly more than N-1. That one-day lower
+     * tolerance absorbs both the execution time between the two clock reads and
+     * a DST hour (moment's calendar add is timezone-aware), while still pinning
+     * the lifetime to exactly N days — it cannot be confused with N-1 or N+1.
+     */
+    const oneDayMs: number = 24 * 60 * 60 * 1000;
+    const msOut: number =
+      created.expires!.getTime() - OneUptimeDate.getCurrentDate().getTime();
+    const expectedMs: number = REGISTRATION_TOKEN_EXPIRY_IN_DAYS * oneDayMs;
+
+    expect(msOut).toBeLessThanOrEqual(expectedMs);
+    expect(msOut).toBeGreaterThan(expectedMs - oneDayMs);
+
+    // It lasts days, not the 24 hours a plain verification link gets.
+    expect(REGISTRATION_TOKEN_EXPIRY_IN_DAYS).toBeGreaterThan(1);
+  });
+});
+
+describe("UserRegistrationToken.getRegistrationLink", () => {
+  test("points at the register page and carries both the address and the token", async () => {
+    const link: URL = await UserRegistrationToken.getRegistrationLink({
+      email: INVITED_EMAIL,
+      token: TOKEN,
+    });
+
+    const asString: string = link.toString();
+
+    expect(asString).toContain("/accounts/register");
+    expect(asString).toContain(encodeURIComponent(INVITED_EMAIL.toString()));
+    expect(asString).toContain(TOKEN.toString());
+  });
+
+  test("generateRegistrationLink mints a token and puts that same token on the link", async () => {
+    const link: URL = await UserRegistrationToken.generateRegistrationLink({
+      userId: USER_ID,
+      email: INVITED_EMAIL,
+    });
+
+    const created: EmailVerificationToken = createSpy.mock.calls[0]![0][
+      "data"
+    ] as EmailVerificationToken;
+
+    expect(link.toString()).toContain(created.token!.toString());
+  });
+});
+
+describe("UserRegistrationToken.consumeRegistrationToken", () => {
+  test("accepts a live token minted for this address", async () => {
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(true);
+  });
+
+  test("spends it, so it cannot be replayed", async () => {
+    await UserRegistrationToken.consumeRegistrationToken({
+      token: TOKEN,
+      email: INVITED_EMAIL,
+    });
+
+    expect(deleteOneBySpy).toHaveBeenCalledTimes(1);
+
+    const query: Record<string, any> = deleteOneBySpy.mock.calls[0]![0][
+      "query"
+    ] as Record<string, any>;
+
+    expect(query["_id"].toString()).toBe(TOKEN_ROW_ID.toString());
+  });
+
+  test("refuses a token that does not exist", async () => {
+    findOneBySpy.mockResolvedValue(null);
+
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+    expect(deleteOneBySpy).not.toHaveBeenCalled();
+  });
+
+  test("refuses a token minted for somebody else's address", async () => {
+    /*
+     * The cross-invitation case. Mallory has a real invitation of her own, so
+     * she holds a real live token -- it just is not for Alice's address, and
+     * without this check it would open Alice's unclaimed account.
+     */
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: OTHER_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+    expect(deleteOneBySpy).not.toHaveBeenCalled();
+  });
+
+  test("matches the address case-insensitively", async () => {
+    /*
+     * Email lowercases on construction, so an invitation sent to Alice@ and a
+     * form filled in as alice@ are the same mailbox and must not be refused.
+     */
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: new Email("ALICE@company.com"),
+      });
+
+    expect(accepted).toBe(true);
+  });
+
+  test("refuses an expired token", async () => {
+    findOneBySpy.mockResolvedValue(
+      tokenRow({ expires: OneUptimeDate.getSomeDaysAgo(1) }),
+    );
+
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+    expect(deleteOneBySpy).not.toHaveBeenCalled();
+  });
+
+  test("refuses a row with no expiry rather than treating it as immortal", async () => {
+    findOneBySpy.mockResolvedValue(tokenRow({ expires: undefined }));
+
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+    expect(deleteOneBySpy).not.toHaveBeenCalled();
+  });
+
+  test("refuses a row with no address rather than treating it as a match", async () => {
+    findOneBySpy.mockResolvedValue(tokenRow({ email: undefined }));
+
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+    expect(deleteOneBySpy).not.toHaveBeenCalled();
+  });
+
+  test("loses the race gracefully when another request spent it first", async () => {
+    /*
+     * Two requests can both read a live token before either deletes it. The
+     * delete is the tiebreak: whoever removes the row won, and the one that
+     * removed nothing is told no.
+     */
+    deleteOneBySpy.mockResolvedValue(0);
+
+    const accepted: boolean =
+      await UserRegistrationToken.consumeRegistrationToken({
+        token: TOKEN,
+        email: INVITED_EMAIL,
+      });
+
+    expect(accepted).toBe(false);
+  });
+
+  test("looks the token up by the token itself", async () => {
+    await UserRegistrationToken.consumeRegistrationToken({
+      token: TOKEN,
+      email: INVITED_EMAIL,
+    });
+
+    const query: Record<string, any> = findOneBySpy.mock.calls[0]![0][
+      "query"
+    ] as Record<string, any>;
+
+    expect(query["token"].toString()).toBe(TOKEN.toString());
+  });
+});

package/Tests/Server/Utils/VerificationCode.test.ts

@@ -0,0 +1,296 @@
+import VerificationCode, {
+  VERIFICATION_CODE_LENGTH,
+} from "../../../Server/Utils/VerificationCode";
+import ObjectID from "../../../Types/ObjectID";
+import { describe, expect, it } from "@jest/globals";
+import crypto from "crypto";
+
+/*
+ * GHSA-5cr8-vph4-3hrf.
+ *
+ * The cryptography under notification-channel verification: a code drawn from
+ * a real CSPRNG, stored only as a keyed digest that is domain-separated by the
+ * row it belongs to, and compared in constant time.
+ */
+describe("VerificationCode", () => {
+  describe("generate", () => {
+    it("produces a six digit code by default", () => {
+      const code: string = VerificationCode.generate();
+
+      expect(code).toHaveLength(VERIFICATION_CODE_LENGTH);
+      expect(code).toMatch(/^[0-9]{6}$/);
+    });
+
+    it("honours an explicit length", () => {
+      expect(VerificationCode.generate(8)).toMatch(/^[0-9]{8}$/);
+      expect(VerificationCode.generate(4)).toMatch(/^[0-9]{4}$/);
+    });
+
+    /*
+     * The whole point of this module existing separately from
+     * Common/Types/Text: Text has to tolerate a runtime without a CSPRNG
+     * because it is bundled into the browser, and falls back to Math.random
+     * there. A code minted on the server must never take that path.
+     */
+    it("never falls back to Math.random", () => {
+      const mathRandomSpy: jest.SpyInstance = jest.spyOn(Math, "random");
+
+      try {
+        for (let i: number = 0; i < 200; i++) {
+          VerificationCode.generate();
+        }
+
+        expect(mathRandomSpy).not.toHaveBeenCalled();
+      } finally {
+        mathRandomSpy.mockRestore();
+      }
+    });
+
+    it("draws from crypto.randomInt", () => {
+      const randomIntSpy: jest.SpyInstance = jest.spyOn(crypto, "randomInt");
+
+      try {
+        VerificationCode.generate(6);
+
+        expect(randomIntSpy).toHaveBeenCalledTimes(6);
+        expect(randomIntSpy).toHaveBeenCalledWith(0, 10);
+      } finally {
+        randomIntSpy.mockRestore();
+      }
+    });
+
+    it("keeps leading zeros, so the code space really is 10^6", () => {
+      let sawLeadingZero: boolean = false;
+
+      for (let i: number = 0; i < 500; i++) {
+        if (VerificationCode.generate().startsWith("0")) {
+          sawLeadingZero = true;
+          break;
+        }
+      }
+
+      expect(sawLeadingZero).toBe(true);
+    });
+
+    it("spreads across the space rather than repeating itself", () => {
+      const seen: Set<string> = new Set<string>();
+
+      for (let i: number = 0; i < 500; i++) {
+        seen.add(VerificationCode.generate());
+      }
+
+      /*
+       * 500 draws from 10^6 values: the birthday bound puts the expected
+       * number of collisions at well under one, so anything below 490 means
+       * the generator is not spreading.
+       */
+      expect(seen.size).toBeGreaterThan(490);
+    });
+
+    it("uses every digit in every position", () => {
+      const perPosition: Array<Set<string>> = [
+        new Set<string>(),
+        new Set<string>(),
+        new Set<string>(),
+        new Set<string>(),
+        new Set<string>(),
+        new Set<string>(),
+      ];
+
+      for (let i: number = 0; i < 2000; i++) {
+        const code: string = VerificationCode.generate();
+
+        for (let position: number = 0; position < 6; position++) {
+          (perPosition[position] as Set<string>).add(code.charAt(position));
+        }
+      }
+
+      for (const position of perPosition) {
+        expect(position.size).toBe(10);
+      }
+    });
+  });
+
+  describe("hashCode", () => {
+    const channelId: ObjectID = new ObjectID(
+      "8f7c1a1a-4bb0-4f0d-9f01-1c0d0d0d0d01",
+    );
+
+    it("returns a 64 character hex digest", () => {
+      expect(VerificationCode.hashCode({ code: "123456", channelId })).toMatch(
+        /^[0-9a-f]{64}$/,
+      );
+    });
+
+    it("is deterministic for the same code and row", () => {
+      expect(VerificationCode.hashCode({ code: "123456", channelId })).toBe(
+        VerificationCode.hashCode({ code: "123456", channelId }),
+      );
+    });
+
+    it("never returns the code itself", () => {
+      const digest: string = VerificationCode.hashCode({
+        code: "123456",
+        channelId,
+      });
+
+      expect(digest).not.toBe("123456");
+      expect(digest).not.toContain("123456");
+    });
+
+    it("changes completely when a single digit changes", () => {
+      const a: string = VerificationCode.hashCode({
+        code: "123456",
+        channelId,
+      });
+      const b: string = VerificationCode.hashCode({
+        code: "123457",
+        channelId,
+      });
+
+      expect(a).not.toBe(b);
+    });
+
+    /*
+     * Domain separation. Without the row id in the message, one precomputed
+     * table of 10^6 digests would invert every row in the table at once, and
+     * two rows that happened to draw the same code would be visibly equal to
+     * anybody holding a database dump.
+     */
+    it("gives the same code different digests on different rows", () => {
+      const otherChannelId: ObjectID = new ObjectID(
+        "8f7c1a1a-4bb0-4f0d-9f01-1c0d0d0d0d02",
+      );
+
+      expect(VerificationCode.hashCode({ code: "123456", channelId })).not.toBe(
+        VerificationCode.hashCode({
+          code: "123456",
+          channelId: otherChannelId,
+        }),
+      );
+    });
+
+    /*
+     * Length-prefixing. Without it, ("ab", "cde") and ("abc", "de") would
+     * concatenate to the same message — the id and code fields could be slid
+     * past each other to forge a digest for a different pair.
+     */
+    it("cannot be confused by moving a character between the id and the code", () => {
+      const first: string = VerificationCode.hashCode({
+        code: "3456",
+        channelId: new ObjectID("ab12"),
+      });
+      const second: string = VerificationCode.hashCode({
+        code: "23456",
+        channelId: new ObjectID("ab1"),
+      });
+
+      expect(first).not.toBe(second);
+    });
+
+    it("is keyed, not a bare digest of its inputs", () => {
+      const digest: string = VerificationCode.hashCode({
+        code: "123456",
+        channelId,
+      });
+
+      const unkeyed: string = crypto
+        .createHash("sha256")
+        .update(`${channelId.toString()}123456`)
+        .digest("hex");
+
+      expect(digest).not.toBe(unkeyed);
+    });
+  });
+
+  describe("isHashEqual", () => {
+    it("accepts identical digests", () => {
+      const digest: string = VerificationCode.hashCode({
+        code: "123456",
+        channelId: new ObjectID("row-1"),
+      });
+
+      expect(VerificationCode.isHashEqual(digest, digest)).toBe(true);
+    });
+
+    it("rejects different digests", () => {
+      const channelId: ObjectID = new ObjectID("row-1");
+
+      expect(
+        VerificationCode.isHashEqual(
+          VerificationCode.hashCode({ code: "123456", channelId }),
+          VerificationCode.hashCode({ code: "654321", channelId }),
+        ),
+      ).toBe(false);
+    });
+
+    it("rejects empty and mismatched-length values without throwing", () => {
+      /*
+       * timingSafeEqual throws on differing lengths, so the guard in front of
+       * it is load-bearing rather than cosmetic.
+       */
+      expect(VerificationCode.isHashEqual("", "")).toBe(false);
+      expect(VerificationCode.isHashEqual("abc", "")).toBe(false);
+      expect(VerificationCode.isHashEqual("", "abc")).toBe(false);
+      expect(VerificationCode.isHashEqual("abc", "abcd")).toBe(false);
+    });
+
+    it("compares with a constant-time primitive rather than ===", () => {
+      const timingSafeEqualSpy: jest.SpyInstance = jest.spyOn(
+        crypto,
+        "timingSafeEqual",
+      );
+
+      try {
+        const digest: string = VerificationCode.hashCode({
+          code: "123456",
+          channelId: new ObjectID("row-1"),
+        });
+
+        VerificationCode.isHashEqual(digest, digest);
+
+        expect(timingSafeEqualSpy).toHaveBeenCalled();
+      } finally {
+        timingSafeEqualSpy.mockRestore();
+      }
+    });
+  });
+
+  describe("generateUnusableHash", () => {
+    it("looks like a digest, so a stored value gives nothing away", () => {
+      expect(VerificationCode.generateUnusableHash()).toMatch(/^[0-9a-f]{64}$/);
+    });
+
+    it("is different every time", () => {
+      const seen: Set<string> = new Set<string>();
+
+      for (let i: number = 0; i < 100; i++) {
+        seen.add(VerificationCode.generateUnusableHash());
+      }
+
+      expect(seen.size).toBe(100);
+    });
+
+    /*
+     * The property that makes it a safe "no live code" marker: no six-digit
+     * code hashes to it. Exhausting 10^6 codes per assertion is not something
+     * a unit test can do, so this samples — the real guarantee is that the
+     * value comes from a 256-bit space the 10^6 digests cannot cover.
+     */
+    it("is not the digest of any code that happens to be tried against it", () => {
+      const channelId: ObjectID = new ObjectID("row-1");
+      const unusable: string = VerificationCode.generateUnusableHash();
+
+      for (let i: number = 0; i < 2000; i++) {
+        const code: string = i.toString().padStart(6, "0");
+
+        expect(
+          VerificationCode.isHashEqual(
+            VerificationCode.hashCode({ code, channelId }),
+            unusable,
+          ),
+        ).toBe(false);
+      }
+    });
+  });
+});