@oneuptime/common 11.7.4 → 12.0.0

package/Tests/Utils/Rum/Masking.test.ts

@@ -0,0 +1,186 @@
+import Masking from "../../../Utils/Rum/Masking";
+
+describe("Masking", () => {
+  describe("maskInputValue", () => {
+    it("is NOT length preserving", () => {
+      /*
+       * This is the single most important assertion in the masking suite.
+       * rrweb's built-in mask is '*'.repeat(value.length), which turns
+       * every masked field into a length oracle: it narrows a password
+       * search space and it identifies a 16-digit value as a card number.
+       * Our mask must be constant width regardless of input.
+       */
+      const short: string = Masking.maskInputValue();
+      const long: string = Masking.maskInputValue();
+
+      expect(short).toBe(long);
+      expect(short.length).toBe(3);
+    });
+
+    it("emits the same mask for values of wildly different lengths", () => {
+      const lengths: Array<number> = [1, 4, 8, 16, 32, 256];
+
+      const masks: Array<string> = lengths.map((): string => {
+        return Masking.maskInputValue();
+      });
+
+      const unique: Set<string> = new Set(masks);
+
+      expect(unique.size).toBe(1);
+    });
+
+    it("masks an empty value too, so cleared and untouched are indistinguishable", () => {
+      expect(Masking.maskInputValue().length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("maskText", () => {
+    it("buckets rather than preserving exact length", () => {
+      /*
+       * Static text is bucketed rather than fixed-width so a wireframe
+       * replay keeps usable layout, but two different strings in the same
+       * bucket must be indistinguishable.
+       */
+      expect(Masking.maskText("hello wo")).toBe(Masking.maskText("goodbye!"));
+    });
+
+    it("maps the three size classes to three distinct widths", () => {
+      const shortMask: string = Masking.maskText("abc");
+      const mediumMask: string = Masking.maskText("a".repeat(20));
+      const longMask: string = Masking.maskText("a".repeat(200));
+
+      expect(shortMask.length).toBe(4);
+      expect(mediumMask.length).toBe(16);
+      expect(longMask.length).toBe(40);
+    });
+
+    it("never leaks the original characters", () => {
+      const secret: string = "Order #4815162342 for jane@example.com";
+      const masked: string = Masking.maskText(secret);
+
+      expect(masked).not.toContain("4815162342");
+      expect(masked).not.toContain("jane@example.com");
+      expect(masked).not.toContain("Order");
+    });
+
+    it("caps the leak to a coarse size class for very long text", () => {
+      /*
+       * A 200-char and a 20,000-char paragraph must produce the same
+       * mask, so the mask cannot be used to fingerprint page content.
+       */
+      expect(Masking.maskText("a".repeat(200))).toBe(
+        Masking.maskText("a".repeat(20000)),
+      );
+    });
+
+    it("leaves whitespace-only text untouched so spacing survives", () => {
+      expect(Masking.maskText("   ")).toBe("   ");
+      expect(Masking.maskText("\n\t")).toBe("\n\t");
+    });
+
+    it("returns empty input unchanged", () => {
+      expect(Masking.maskText("")).toBe("");
+    });
+  });
+
+  describe("maskFileInputValue", () => {
+    it("always blanks the value", () => {
+      /*
+       * A file input's DOM value is C:\fakepath\<real filename>, and
+       * filenames are routinely personal — "passport-scan.pdf",
+       * "payslip-march.pdf", "biopsy-results.pdf".
+       */
+      expect(Masking.maskFileInputValue()).toBe("");
+    });
+  });
+
+  describe("isAlwaysSensitiveInputType", () => {
+    it("treats password as always sensitive", () => {
+      expect(Masking.isAlwaysSensitiveInputType("password")).toBe(true);
+      expect(Masking.isAlwaysSensitiveInputType("PASSWORD")).toBe(true);
+    });
+
+    it("does not treat ordinary types as always sensitive", () => {
+      expect(Masking.isAlwaysSensitiveInputType("text")).toBe(false);
+      expect(Masking.isAlwaysSensitiveInputType("checkbox")).toBe(false);
+      expect(Masking.isAlwaysSensitiveInputType("")).toBe(false);
+    });
+  });
+
+  describe("isStickySensitiveAutocomplete", () => {
+    it("recognises credential and one-time-code fields", () => {
+      expect(Masking.isStickySensitiveAutocomplete("current-password")).toBe(
+        true,
+      );
+      expect(Masking.isStickySensitiveAutocomplete("new-password")).toBe(true);
+      expect(Masking.isStickySensitiveAutocomplete("one-time-code")).toBe(true);
+    });
+
+    it("recognises card fields, which are type=text and so invisible to type checks", () => {
+      /*
+       * rrweb keys masking on HTML input *type*. A card number field is
+       * type="text", so autocomplete is the only durable signal short of
+       * a cross-origin PSP iframe.
+       */
+      expect(Masking.isStickySensitiveAutocomplete("cc-number")).toBe(true);
+      expect(Masking.isStickySensitiveAutocomplete("cc-csc")).toBe(true);
+      expect(Masking.isStickySensitiveAutocomplete("cc-exp")).toBe(true);
+    });
+
+    it("handles the multi-token form with section and billing prefixes", () => {
+      /*
+       * autocomplete legitimately reads "section-payment billing cc-number",
+       * so a whole-string comparison would miss real card fields.
+       */
+      expect(
+        Masking.isStickySensitiveAutocomplete(
+          "section-payment billing cc-number",
+        ),
+      ).toBe(true);
+      expect(Masking.isStickySensitiveAutocomplete("shipping cc-csc")).toBe(
+        true,
+      );
+    });
+
+    it("is case-insensitive", () => {
+      expect(Masking.isStickySensitiveAutocomplete("CC-NUMBER")).toBe(true);
+    });
+
+    it("does not over-match ordinary autocomplete values", () => {
+      expect(Masking.isStickySensitiveAutocomplete("email")).toBe(false);
+      expect(Masking.isStickySensitiveAutocomplete("name")).toBe(false);
+      expect(Masking.isStickySensitiveAutocomplete("off")).toBe(false);
+      expect(Masking.isStickySensitiveAutocomplete("")).toBe(false);
+    });
+  });
+
+  describe("quantiseTimestamp", () => {
+    it("floors timestamps into buckets", () => {
+      expect(Masking.quantiseTimestamp(1000, 250)).toBe(1000);
+      expect(Masking.quantiseTimestamp(1123, 250)).toBe(1000);
+      expect(Masking.quantiseTimestamp(1249, 250)).toBe(1000);
+      expect(Masking.quantiseTimestamp(1250, 250)).toBe(1250);
+    });
+
+    it("removes inter-keystroke timing resolution", () => {
+      /*
+       * A masked password field still leaks typed content through
+       * keystroke timing, which is a published side channel. Bucketing
+       * collapses realistic keystroke gaps to a single value.
+       */
+      const keystrokes: Array<number> = [1000, 1040, 1095, 1160, 1210];
+
+      const quantised: Array<number> = keystrokes.map((t: number): number => {
+        return Masking.quantiseTimestamp(t, 250);
+      });
+
+      expect(new Set(quantised).size).toBe(1);
+    });
+
+    it("passes through non-finite input and non-positive buckets unchanged", () => {
+      expect(Masking.quantiseTimestamp(Number.NaN, 250)).toBeNaN();
+      expect(Masking.quantiseTimestamp(1234, 0)).toBe(1234);
+      expect(Masking.quantiseTimestamp(1234, -5)).toBe(1234);
+    });
+  });
+});

package/Tests/Utils/Rum/SessionIdentity.test.ts

@@ -0,0 +1,272 @@
+import SessionIdentity, {
+  SessionRotationReason,
+  StoredSessionState,
+} from "../../../Utils/Rum/SessionIdentity";
+
+const NOW: number = 1_700_000_000_000;
+const MINUTE: number = 60 * 1000;
+const HOUR: number = 60 * MINUTE;
+
+const makeState: (
+  overrides?: Partial<StoredSessionState>,
+) => StoredSessionState = (
+  overrides?: Partial<StoredSessionState>,
+): StoredSessionState => {
+  return {
+    sessionId: "3f1a9c7e5b2d4801f6a3c9e7b1d5028f",
+    sessionStartUnixMs: NOW - 5 * MINUTE,
+    lastActivityUnixMs: NOW - MINUTE,
+    ...overrides,
+  };
+};
+
+describe("SessionIdentity", () => {
+  describe("shouldRotateSession", () => {
+    it("rotates when there is no stored session", () => {
+      const decision: ReturnType<typeof SessionIdentity.shouldRotateSession> =
+        SessionIdentity.shouldRotateSession(null, NOW);
+
+      expect(decision.shouldRotate).toBe(true);
+      expect(decision.reason).toBe(SessionRotationReason.New);
+    });
+
+    it("keeps an active session", () => {
+      expect(
+        SessionIdentity.shouldRotateSession(makeState(), NOW).shouldRotate,
+      ).toBe(false);
+    });
+
+    it("rotates after the idle window elapses", () => {
+      /*
+       * A single "session" that spans a lunch break is not a session, and
+       * stitching one produces a recording with a 40-minute dead zone.
+       */
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW - 40 * MINUTE,
+        lastActivityUnixMs: NOW - 31 * MINUTE,
+      });
+
+      const decision: ReturnType<typeof SessionIdentity.shouldRotateSession> =
+        SessionIdentity.shouldRotateSession(state, NOW);
+
+      expect(decision.shouldRotate).toBe(true);
+      expect(decision.reason).toBe(SessionRotationReason.Idle);
+    });
+
+    it("does not rotate one millisecond before the idle boundary", () => {
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW - 40 * MINUTE,
+        lastActivityUnixMs: NOW - (30 * MINUTE - 1),
+      });
+
+      expect(SessionIdentity.shouldRotateSession(state, NOW).shouldRotate).toBe(
+        false,
+      );
+    });
+
+    it("rotates exactly at the idle boundary", () => {
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW - 40 * MINUTE,
+        lastActivityUnixMs: NOW - 30 * MINUTE,
+      });
+
+      expect(SessionIdentity.shouldRotateSession(state, NOW).reason).toBe(
+        SessionRotationReason.Idle,
+      );
+    });
+
+    it("rotates at the absolute duration cap even while still active", () => {
+      /*
+       * A tab left open for days would otherwise accumulate an unbounded
+       * chunk sequence under a single sort-key prefix.
+       */
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW - 5 * HOUR,
+        lastActivityUnixMs: NOW - 1000,
+      });
+
+      const decision: ReturnType<typeof SessionIdentity.shouldRotateSession> =
+        SessionIdentity.shouldRotateSession(state, NOW);
+
+      expect(decision.shouldRotate).toBe(true);
+      expect(decision.reason).toBe(SessionRotationReason.DurationCap);
+    });
+
+    it("prefers the idle reason when both conditions hold", () => {
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW - 5 * HOUR,
+        lastActivityUnixMs: NOW - 2 * HOUR,
+      });
+
+      expect(SessionIdentity.shouldRotateSession(state, NOW).reason).toBe(
+        SessionRotationReason.Idle,
+      );
+    });
+
+    it("rotates on corrupt stored state rather than trusting it", () => {
+      /*
+       * Trusting inconsistent state can attribute one user's chunks to
+       * another user's session id. A fresh session loses a little context;
+       * a mis-attributed session is a privacy incident.
+       */
+      const corruptStates: Array<StoredSessionState> = [
+        makeState({ sessionId: "" }),
+        makeState({ sessionStartUnixMs: Number.NaN }),
+        makeState({ lastActivityUnixMs: Number.NaN }),
+        makeState({ sessionStartUnixMs: 0 }),
+        makeState({ lastActivityUnixMs: -1 }),
+        /* Activity before the session started. */
+        makeState({
+          sessionStartUnixMs: NOW - MINUTE,
+          lastActivityUnixMs: NOW - 10 * MINUTE,
+        }),
+        /* Stamped far in the future: clock jump or tampering. */
+        makeState({ sessionStartUnixMs: NOW + HOUR }),
+      ];
+
+      for (const state of corruptStates) {
+        const decision: ReturnType<typeof SessionIdentity.shouldRotateSession> =
+          SessionIdentity.shouldRotateSession(state, NOW);
+
+        expect(decision.shouldRotate).toBe(true);
+        expect(decision.reason).toBe(SessionRotationReason.Corrupt);
+      }
+    });
+
+    it("tolerates small forward skew from a corrected device clock", () => {
+      const state: StoredSessionState = makeState({
+        sessionStartUnixMs: NOW + 30 * 1000,
+        lastActivityUnixMs: NOW + 30 * 1000,
+      });
+
+      expect(SessionIdentity.shouldRotateSession(state, NOW).shouldRotate).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("clampSessionStart", () => {
+    it("passes through a sane client timestamp", () => {
+      expect(SessionIdentity.clampSessionStart(NOW - MINUTE, NOW)).toBe(
+        NOW - MINUTE,
+      );
+    });
+
+    it("clamps a future client clock to the server clock", () => {
+      /*
+       * The clamped value lands in the partition key and the TTL
+       * expression. A device clock set to 2035 would otherwise create a
+       * partition that never expires.
+       */
+      const yearAhead: number = NOW + 365 * 24 * HOUR;
+
+      expect(SessionIdentity.clampSessionStart(yearAhead, NOW)).toBe(NOW);
+    });
+
+    it("clamps an ancient client clock forward to the acceptance window", () => {
+      /*
+       * A device clock set to 2015 would otherwise produce a row whose
+       * retentionDate is already past, deleting it on arrival.
+       */
+      const decadeAgo: number = NOW - 10 * 365 * 24 * HOUR;
+
+      expect(SessionIdentity.clampSessionStart(decadeAgo, NOW)).toBe(
+        NOW - 4 * HOUR,
+      );
+    });
+
+    it("falls back to the server clock for non-finite input", () => {
+      expect(SessionIdentity.clampSessionStart(Number.NaN, NOW)).toBe(NOW);
+    });
+
+    it("always returns a value inside the acceptance window", () => {
+      const inputs: Array<number> = [
+        0,
+        -1,
+        NOW,
+        NOW - HOUR,
+        NOW + HOUR,
+        Number.MAX_SAFE_INTEGER,
+        Number.MIN_SAFE_INTEGER,
+      ];
+
+      for (const input of inputs) {
+        const clamped: number = SessionIdentity.clampSessionStart(input, NOW);
+
+        expect(clamped).toBeLessThanOrEqual(NOW);
+        expect(clamped).toBeGreaterThanOrEqual(NOW - 4 * HOUR);
+      }
+    });
+  });
+
+  describe("getClockSkewMs", () => {
+    it("is positive when the client clock runs ahead", () => {
+      expect(SessionIdentity.getClockSkewMs(NOW + 5000, NOW)).toBe(5000);
+    });
+
+    it("is negative when the client clock lags", () => {
+      expect(SessionIdentity.getClockSkewMs(NOW - 5000, NOW)).toBe(-5000);
+    });
+
+    it("returns zero rather than NaN for unusable input", () => {
+      expect(SessionIdentity.getClockSkewMs(Number.NaN, NOW)).toBe(0);
+      expect(SessionIdentity.getClockSkewMs(NOW, Number.NaN)).toBe(0);
+    });
+  });
+
+  describe("clampRetentionDays", () => {
+    const allowed: Array<number> = [1, 7, 14, 30, 90];
+
+    it("passes through an exact allowed value", () => {
+      for (const days of allowed) {
+        expect(SessionIdentity.clampRetentionDays(days, allowed, 7)).toBe(days);
+      }
+    });
+
+    it("rounds UP to the next allowed value", () => {
+      /*
+       * Rounding up is deliberate: silently shortening a customer's
+       * configured retention destroys evidence they expected to keep,
+       * whereas keeping it a little longer only costs disk.
+       */
+      expect(SessionIdentity.clampRetentionDays(2, allowed, 7)).toBe(7);
+      expect(SessionIdentity.clampRetentionDays(8, allowed, 7)).toBe(14);
+      expect(SessionIdentity.clampRetentionDays(31, allowed, 7)).toBe(90);
+    });
+
+    it("caps at the largest allowed value", () => {
+      expect(SessionIdentity.clampRetentionDays(365, allowed, 7)).toBe(90);
+    });
+
+    it("falls back for non-positive or non-finite input", () => {
+      expect(SessionIdentity.clampRetentionDays(0, allowed, 7)).toBe(7);
+      expect(SessionIdentity.clampRetentionDays(-5, allowed, 7)).toBe(7);
+      expect(SessionIdentity.clampRetentionDays(Number.NaN, allowed, 7)).toBe(
+        7,
+      );
+    });
+
+    it("falls back when the allowed set is empty", () => {
+      expect(SessionIdentity.clampRetentionDays(30, [], 7)).toBe(7);
+    });
+
+    it("handles an unsorted allowed set", () => {
+      expect(SessionIdentity.clampRetentionDays(8, [90, 1, 30, 7, 14], 7)).toBe(
+        14,
+      );
+    });
+
+    it("only ever returns a member of the allowed set", () => {
+      /*
+       * This is the load-bearing property: each distinct retention value
+       * creates its own ClickHouse partition per ingest day, so an
+       * unclamped value is a partition-count problem, not just a policy one.
+       */
+      for (let days: number = -5; days <= 400; days++) {
+        expect(allowed).toContain(
+          SessionIdentity.clampRetentionDays(days, allowed, 7),
+        );
+      }
+    });
+  });
+});

package/Tests/Utils/Rum/SessionSampling.test.ts

@@ -0,0 +1,164 @@
+import SessionSampling from "../../../Utils/Rum/SessionSampling";
+
+describe("SessionSampling", () => {
+  describe("fnv1a32", () => {
+    it("returns the published FNV-1a 32-bit vectors", () => {
+      /*
+       * Reference vectors from the FNV specification. If these drift, the
+       * server and the browser recorder will disagree about which sessions
+       * are sampled, and sessions will be half-recorded.
+       */
+      expect(SessionSampling.fnv1a32("")).toBe(0x811c9dc5);
+      expect(SessionSampling.fnv1a32("a")).toBe(0xe40c292c);
+      expect(SessionSampling.fnv1a32("foobar")).toBe(0xbf9cf968);
+    });
+
+    it("always returns an unsigned 32-bit integer", () => {
+      /*
+       * The multiply must stay in integer space. A plain `*` overflows to
+       * a float and silently stops distributing, which would not fail any
+       * naive equality test — so assert the range over many inputs.
+       */
+      for (let i: number = 0; i < 2000; i++) {
+        const hash: number = SessionSampling.fnv1a32(`session-${i}`);
+
+        expect(Number.isInteger(hash)).toBe(true);
+        expect(hash).toBeGreaterThanOrEqual(0);
+        expect(hash).toBeLessThanOrEqual(0xffffffff);
+      }
+    });
+
+    it("is stable across calls", () => {
+      expect(SessionSampling.fnv1a32("abc123")).toBe(
+        SessionSampling.fnv1a32("abc123"),
+      );
+    });
+  });
+
+  describe("getBucket", () => {
+    it("returns a bucket in [0, 10000)", () => {
+      for (let i: number = 0; i < 2000; i++) {
+        const bucket: number = SessionSampling.getBucket(`s-${i}`);
+
+        expect(bucket).toBeGreaterThanOrEqual(0);
+        expect(bucket).toBeLessThan(10000);
+      }
+    });
+  });
+
+  describe("isSampled", () => {
+    it("samples nothing at 0 percent", () => {
+      for (let i: number = 0; i < 500; i++) {
+        expect(SessionSampling.isSampled(`session-${i}`, 0)).toBe(false);
+      }
+    });
+
+    it("samples everything at 100 percent", () => {
+      for (let i: number = 0; i < 500; i++) {
+        expect(SessionSampling.isSampled(`session-${i}`, 100)).toBe(true);
+      }
+    });
+
+    it("is deterministic for the same session id", () => {
+      const sessionId: string = "3f1a9c7e5b2d4801f6a3c9e7b1d5028f";
+
+      const first: boolean = SessionSampling.isSampled(sessionId, 37.5);
+
+      for (let i: number = 0; i < 50; i++) {
+        expect(SessionSampling.isSampled(sessionId, 37.5)).toBe(first);
+      }
+    });
+
+    it("lands within a couple of points of the requested rate over a large population", () => {
+      /*
+       * The whole point of hashing rather than counting is that the rate
+       * emerges from the distribution. A skewed hash would still be
+       * deterministic and would still pass the tests above, so the
+       * distribution itself has to be asserted.
+       */
+      const population: number = 20000;
+
+      for (const percentage of [1, 10, 25, 50, 90]) {
+        let sampled: number = 0;
+
+        for (let i: number = 0; i < population; i++) {
+          if (
+            SessionSampling.isSampled(`sess-${percentage}-${i}`, percentage)
+          ) {
+            sampled++;
+          }
+        }
+
+        const observed: number = (sampled / population) * 100;
+
+        expect(Math.abs(observed - percentage)).toBeLessThan(2);
+      }
+    });
+
+    it("is monotonic in the sample percentage", () => {
+      /*
+       * Raising the rate must never *unsample* a session that was already
+       * in. Anything else means a customer who increases sampling loses
+       * recordings they were previously getting.
+       */
+      const sessionIds: Array<string> = Array.from(
+        { length: 500 },
+        (_unused: unknown, i: number): string => {
+          return `mono-${i}`;
+        },
+      );
+
+      for (const sessionId of sessionIds) {
+        let wasSampled: boolean = false;
+
+        for (const percentage of [0, 5, 10, 25, 50, 75, 100]) {
+          const isSampled: boolean = SessionSampling.isSampled(
+            sessionId,
+            percentage,
+          );
+
+          if (wasSampled) {
+            expect(isSampled).toBe(true);
+          }
+
+          wasSampled = isSampled;
+        }
+      }
+    });
+
+    it("clamps out-of-range percentages instead of throwing", () => {
+      expect(SessionSampling.isSampled("x", -10)).toBe(false);
+      expect(SessionSampling.isSampled("x", 1000)).toBe(true);
+    });
+
+    it("fails closed on a non-finite percentage", () => {
+      /*
+       * A garbage sample rate must record nobody, not everybody. NaN and
+       * Infinity both mean "this config is broken", and for a feature that
+       * records real end users' screens the safe reading of a broken
+       * config is zero, not 100%.
+       */
+      expect(SessionSampling.isSampled("x", Number.NaN)).toBe(false);
+      expect(SessionSampling.isSampled("x", Number.POSITIVE_INFINITY)).toBe(
+        false,
+      );
+      expect(SessionSampling.isSampled("x", Number.NEGATIVE_INFINITY)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("clampPercentage", () => {
+    it("clamps to the 0..100 range", () => {
+      expect(SessionSampling.clampPercentage(-1)).toBe(0);
+      expect(SessionSampling.clampPercentage(0)).toBe(0);
+      expect(SessionSampling.clampPercentage(42.5)).toBe(42.5);
+      expect(SessionSampling.clampPercentage(100)).toBe(100);
+      expect(SessionSampling.clampPercentage(101)).toBe(100);
+    });
+
+    it("treats NaN as zero so a bad config cannot throw on the ingest path", () => {
+      expect(SessionSampling.clampPercentage(Number.NaN)).toBe(0);
+    });
+  });
+});