compare.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1/**
2 * The one constant-time comparison of a presented secret with the expected one. A local copy that drifts toward `===`
3 * leaks the secret a byte at a time and no test notices.
4 *
5 * - Both sides are hashed with SHA-256 first, so what is compared is always 32 bytes against 32 bytes. Comparing the
6 *   strings themselves would leak their lengths through an early return or the loop bound; after hashing, neither
7 *   length reaches the comparison. (The hash itself takes time in proportion to the input's length, which is the
8 *   unavoidable part, and it is the attacker's own input whose length that reveals.)
9 * - The bytes are compared by crypto.subtle.timingSafeEqual where the runtime has it (workerd; Cloudflare's Workers
10 *   best-practices guide names it for secret compares), and by an XOR over all 32 bytes elsewhere (Node, the tests).
11 * - A side that is not a string, or is empty, matches nothing, so an unset secret (`env.KEY` undefined, or "") never
12 *   admits an absent or empty credential.
13 */
14
15/** @param {string} text */
16async function digest(text) {
17  return new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
18}
19
20/**
21 * Two equal-length byte arrays, compared in time that does not depend on where they differ.
22 * @param {Uint8Array<ArrayBuffer>} a
23 * @param {Uint8Array<ArrayBuffer>} b
24 */
25function sameBytes(a, b) {
26  const native = /** @type {{ timingSafeEqual?: (x: BufferSource, y: BufferSource) => boolean }} */ (crypto.subtle).timingSafeEqual;
27  if (typeof native === "function") return native.call(crypto.subtle, a, b);
28  let diff = 0;
29  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
30  return diff === 0;
31}
32
33/**
34 * True when `a` and `b` are the same non-empty string, in time that does not depend on where they differ or on the
35 * expected secret's length.
36 * @param {unknown} a
37 * @param {unknown} b
38 * @returns {Promise<boolean>}
39 */
40export async function safeEqual(a, b) {
41  // Both digests are computed before either check is answered, so a refused type or empty side costs what a compare does.
42  const valid = typeof a === "string" && typeof b === "string" && a !== "" && b !== "";
43  const [left, right] = await Promise.all([digest(typeof a === "string" ? a : ""), digest(typeof b === "string" ? b : "")]);
44  const same = sameBytes(left, right);
45  return valid && same;
46}