crypto: add randomUUIDv7() for RFC 9562 v7 UUIDs

Author: nabeel378

doc/api/crypto.md

@@ -5826,6 +5826,33 @@ added:
 Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a
 cryptographic pseudorandom number generator.
 
+### `crypto.randomUUIDv7()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string}
+
+Generates a random [RFC 9562][] version 7 UUID. The UUID contains a millisecond
+precision Unix timestamp in the most significant 48 bits, followed by
+cryptographically secure random bits for the remaining fields, making it
+suitable for use as a database key with time-based sorting.
+
+```mjs
+import { randomUUIDv7 } from 'node:crypto';
+
+console.log(randomUUIDv7());
+// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
+```
+
+```cjs
+const { randomUUIDv7 } = require('node:crypto');
+
+console.log(randomUUIDv7());
+// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
+```
+
 ### `crypto.scrypt(password, salt, keylen[, options], callback)`
 
 <!-- YAML
@@ -6861,6 +6888,7 @@ See the [list of SSL OP Flags][] for details.
 [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
 [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
+[RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562.txt
 [RFC 5280]: https://www.rfc-editor.org/rfc/rfc5280.txt
 [RFC 7517]: https://www.rfc-editor.org/rfc/rfc7517.txt
 [RFC 8032]: https://www.rfc-editor.org/rfc/rfc8032.txt

lib/crypto.js

@@ -56,6 +56,7 @@ const {
   randomFillSync,
   randomInt,
   randomUUID,
+  randomUUIDv7,
 } = require('internal/crypto/random');
 const {
   argon2,
@@ -220,6 +221,7 @@ module.exports = {
   randomFillSync,
   randomInt,
   randomUUID,
+  randomUUIDv7,
   scrypt,
   scryptSync,
   sign: signOneShot,

lib/internal/crypto/random.js

@@ -11,6 +11,7 @@ const {
   BigIntPrototypeToString,
   DataView,
   DataViewPrototypeGetUint8,
+  DateNow,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
   MathMin,
@@ -414,6 +415,62 @@ function randomUUID(options) {
   return disableEntropyCache ? getUnbufferedUUID() : getBufferedUUID();
 }
 
+// Implements an RFC 9562 version 7 UUID (time-ordered).
+// Layout (128 bits total):
+//   48 bits  - unix_ts_ms: UTC timestamp in milliseconds
+//    4 bits  - version: 0b0111 (7)
+//   12 bits  - rand_a: random
+//    2 bits  - variant: 0b10
+//   62 bits  - rand_b: random
+
+let uuidV7Buffer;
+
+function randomUUIDv7() {
+  uuidV7Buffer ??= secureBuffer(16);
+  if (uuidV7Buffer === undefined)
+    throw new ERR_OPERATION_FAILED('Out of memory');
+
+  // Fill all 16 bytes with random data first.
+  randomFillSync(uuidV7Buffer);
+
+  // Write 48-bit timestamp (ms since Unix epoch) into bytes 0-5, big-endian.
+  const now = DateNow();
+  uuidV7Buffer[0] = (now / 0x10000000000) & 0xff;
+  uuidV7Buffer[1] = (now / 0x100000000) & 0xff;
+  uuidV7Buffer[2] = (now / 0x1000000) & 0xff;
+  uuidV7Buffer[3] = (now / 0x10000) & 0xff;
+  uuidV7Buffer[4] = (now / 0x100) & 0xff;
+  uuidV7Buffer[5] = now & 0xff;
+
+  // Set version (7) in byte 6 high nibble, keep rand_a in low nibble.
+  uuidV7Buffer[6] = (uuidV7Buffer[6] & 0x0f) | 0x70;
+
+  // Set variant (0b10) in byte 8 high 2 bits, keep rand_b in low 6 bits.
+  uuidV7Buffer[8] = (uuidV7Buffer[8] & 0x3f) | 0x80;
+
+  const kHexBytes = getHexBytes();
+  return kHexBytes[uuidV7Buffer[0]] +
+    kHexBytes[uuidV7Buffer[1]] +
+    kHexBytes[uuidV7Buffer[2]] +
+    kHexBytes[uuidV7Buffer[3]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[4]] +
+    kHexBytes[uuidV7Buffer[5]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[6]] +
+    kHexBytes[uuidV7Buffer[7]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[8]] +
+    kHexBytes[uuidV7Buffer[9]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[10]] +
+    kHexBytes[uuidV7Buffer[11]] +
+    kHexBytes[uuidV7Buffer[12]] +
+    kHexBytes[uuidV7Buffer[13]] +
+    kHexBytes[uuidV7Buffer[14]] +
+    kHexBytes[uuidV7Buffer[15]];
+}
+
 function createRandomPrimeJob(type, size, options) {
   validateObject(options, 'options');
 
@@ -611,6 +668,7 @@ module.exports = {
   randomInt,
   getRandomValues,
   randomUUID,
+  randomUUIDv7,
   generatePrime,
   generatePrimeSync,
 };

test/parallel/test-crypto-randomuuidv7.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const common = require('../common');
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const {
+  randomUUIDv7,
+} = require('crypto');
+
+// Basic return type and format checks.
+{
+  const uuid = randomUUIDv7();
+  assert.strictEqual(typeof uuid, 'string');
+  assert.strictEqual(uuid.length, 36);
+
+  // UUIDv7 format: xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx
+  assert.match(
+    uuid,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  );
+}
+
+// Check version and variant bits.
+{
+  const uuid = randomUUIDv7();
+
+  // Version 7: byte 6 high nibble should be 0x7.
+  assert.strictEqual(
+    Buffer.from(uuid.slice(14, 16), 'hex')[0] & 0xf0, 0x70,
+  );
+
+  // Variant: byte 8 high 2 bits should be 0b10.
+  assert.strictEqual(
+    Buffer.from(uuid.slice(19, 21), 'hex')[0] & 0b1100_0000, 0b1000_0000,
+  );
+}
+
+// Uniqueness: generate many UUIDs and verify no duplicates.
+{
+  const seen = new Set();
+  for (let i = 0; i < 1000; i++) {
+    const uuid = randomUUIDv7();
+    assert(!seen.has(uuid), `Duplicate UUID generated: ${uuid}`);
+    seen.add(uuid);
+  }
+}
+
+// Timestamp: the embedded timestamp should approximate Date.now().
+{
+  const before = Date.now();
+  const uuid = randomUUIDv7();
+  const after = Date.now();
+
+  // Extract the 48-bit timestamp from the UUID.
+  // Bytes 0-3 (chars 0-8) and bytes 4-5 (chars 9-13, skipping the dash).
+  const hex = uuid.replace(/-/g, '');
+  const timestampHex = hex.slice(0, 12); // first 48 bits = 12 hex chars
+  const timestamp = parseInt(timestampHex, 16);
+
+  assert(timestamp >= before, `Timestamp ${timestamp} < before ${before}`);
+  assert(timestamp <= after, `Timestamp ${timestamp} > after ${after}`);
+}
+
+// Monotonicity: UUIDs generated in sequence should sort lexicographically
+// within the same millisecond or across milliseconds.
+{
+  let prev = randomUUIDv7();
+  for (let i = 0; i < 100; i++) {
+    const curr = randomUUIDv7();
+    // UUIDs with later timestamps must sort after earlier ones.
+    // Within the same millisecond, ordering depends on random bits,
+    // so we only assert >= on the timestamp portion.
+    const prevTs = parseInt(prev.replace(/-/g, '').slice(0, 12), 16);
+    const currTs = parseInt(curr.replace(/-/g, '').slice(0, 12), 16);
+    assert(currTs >= prevTs,
+           `Timestamp went backwards: ${currTs} < ${prevTs}`);
+    prev = curr;
+  }
+}
+
+// Ensure randomUUIDv7 takes no arguments (or ignores them gracefully).
+{
+  const uuid = randomUUIDv7();
+  assert.match(
+    uuid,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  );
+}