crypto: implement randomUUIDv7()#62553

nabeel378 · 2026-04-02T03:36:50Z

Adds crypto.randomUUIDv7() which generates RFC 9562 version 7 UUIDs.

UUIDv7 encodes a millisecond-precision Unix timestamp in the most
significant 48 bits, making these UUIDs time-sortable and suitable
for use as database primary keys.

Layout (128 bits):

48 bits: unix_ts_ms (UTC milliseconds)
4 bits: version (0b0111)
12 bits: rand_a (random)
2 bits: variant (0b10)
62 bits: rand_b (random)

Fixes: #62529
Refs: https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7

nodejs-github-bot · 2026-04-02T03:36:56Z

Review requested:

@nodejs/crypto

Renegade334

Thanks! A few initial comments.

panva · 2026-04-02T10:51:27Z

A lot of effort went into optimizing the v4 version. We shall make sure to use the same primitives and setup without actually disrupting the v4 one.

At the moment this proposal doesn't align with the options v4 has.

nabeel378 · 2026-04-02T11:19:30Z

A lot of effort went into optimizing the v4 version. We shall make sure to use the same primitives and setup without actually disrupting the v4 one.

At the moment this proposal doesn't align with the options v4 has.

I have updated the implementation to fully align with v4: Added disableEntropyCache option matching randomUUID() Same batching strategy (kBatchSize = 128, secureBuffer, randomFillSync)

panva · 2026-04-02T12:42:51Z

Please change the first commit message to crypto: implement randomUUIDv7() and make sure to use -s git flag to add a Signed-off-by trailer.

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

…dability

…bytes

… cache

- Make version/variant required params in serializeUUID - Share buffer pools (uuidData/uuidNotBuffered) between v4 and v7 Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

aduh95 · 2026-04-03T13:02:35Z

test: retrigger CI

@nabeel378 Please don't do that

nodejs-github-bot · 2026-04-03T13:05:50Z

CI: https://ci.nodejs.org/job/node-test-pull-request/72452/

nabeel378 · 2026-04-03T13:39:01Z

test: retrigger CI

@nabeel378 Please don't do that

Hi @aduh95, thanks for the heads-up! I added an empty commit to retry CI because sequential.test-watch-mode-inspect and node-test-commit-linux-containered tests failed, but I understand I shouldn’t do that.

jasnell · 2026-04-03T14:06:35Z

@nabeel378 ... the github CI is not our main CI. We use jenkins for that and it requires a maintainer to kick it off. Pushing another commit does not trigger the jenkins CI to run again. Also keep in mind that PRs have to stay open for a minimum of 48 hours anyway so trying to rush CI is typically pointless.

nabeel378 · 2026-04-03T14:31:18Z

@jasnell ... Noted, thanks

tniessen

I would prefer if the documentation pointed out that the implementation relies on a non-monotonic clock (because Date.now() merely approximates the current time and itself is not monotonic) and therefore does not guarantee that the timestamps will be in order (even though users should not assume monotonicity anyway).

nabeel378 · 2026-04-04T11:18:56Z

@tniessen is this wording okay, or would you suggest any changes?" 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. The embedded
timestamp relies on a non-monotonic clock and is not guaranteed to be strictly
increasing."

tniessen · 2026-04-04T16:28:19Z

Sure, that works, thank you! (If you don't want to have to re-run CI, I am also okay with updating the docs in a separate PR later.)

Renegade334 · 2026-04-04T17:07:50Z

+1 to not tweaking this PR over it, CI is rolling with disadvantage at present 😉

nodejs-github-bot · 2026-04-05T10:12:23Z

Landed in dec5973

panva · 2026-04-05T11:23:15Z

@nabeel378 Thank you for your contribution, it is much appreciated. Please follow up with a doc only PR as discussed above

nabeel378 · 2026-04-05T11:30:00Z

@nabeel378 Thank you for your contribution, it is much appreciated. Please follow up with a doc only PR as discussed above

@panva yes, I am creating PR.

theoludwig · 2026-04-07T07:56:59Z

Can we add an option similar as the npm package uuid: https://www.npmjs.com/package/uuid#uuidv7 (e.g called msecs) to be able to set "RFC "timestamp" field (Number of milliseconds, unix epoch)"?

nabeel378 · 2026-04-07T08:45:46Z

@theoludwig Thanks for the suggestion!
We prefer keeping the API consistent with crypto.randomUUID() (v4) without exposing internal fields.
Happy to revisit if there’s strong demand.

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com> PR-URL: #62553 Fixes: #62529 Refs: https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com> Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

Notable changes: buffer: * (SEMVER-MINOR) add `end` parameter (Robert Nagy) #62390 crypto: * (SEMVER-MINOR) accept key data in `crypto.diffieHellman()` and cleanup DH jobs (Filip Skokan) #62527 * (SEMVER-MINOR) implement `randomUUIDv7()` (nabeel378) #62553 debugger: * (SEMVER-MINOR) add edit-free runtime expression probes to `node inspect` (Joyee Cheung) #62713 fs: * (SEMVER-MINOR) add `signal` option to `fs.stat()` (Mert Can Altin) #57775 * (SEMVER-MINOR) expose frsize field in statfs (Jinho Jang) #62277 http: * (SEMVER-MINOR) harden `ClientRequest` options merge (Matteo Collina) #63082 * (SEMVER-MINOR) add `req.signal` to `IncomingMessage` (Akshat) #62541 lib,src,test,doc: * (SEMVER-MINOR) add `node:ffi` module (Colin Ihrig) #62072 process: * (SEMVER-MINOR) throw on `execve(2)` failure instead of aborting (Bryan English) #62878 src: * (SEMVER-MINOR) allow empty `--experimental-config-file` (Marco Ippolito) #61610 stream: * (SEMVER-MINOR) propagate destruction in `duplexPair` (Ahmed Elhor) #61098 test_runner: * (SEMVER-MINOR) align mock timeout api (sangwook) #62820 * (SEMVER-MINOR) add mock-timers support for `AbortSignal.timeout` (DeveloperViraj) #60751 * (SEMVER-MINOR) support test order randomization (Pietro Marchini) #61747 util: * (SEMVER-MINOR) colorize text with hex colors (Guilherme Araújo) #61556 PR-URL: #63137

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com> PR-URL: #62553 Fixes: #62529 Refs: https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com> Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>

nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. needs-ci PRs that need a full CI run. labels Apr 2, 2026

nabeel378 mentioned this pull request Apr 2, 2026

Add support for generating UUIDv7s #62529

Closed

nabeel378 force-pushed the main branch from 8e1531c to b1d3efc Compare April 2, 2026 08:59

Renegade334 reviewed Apr 2, 2026

View reviewed changes

Comment thread lib/internal/crypto/random.js Outdated

Comment thread lib/internal/crypto/random.js Outdated

nabeel378 requested a review from Renegade334 April 2, 2026 11:39

panva added the commit-queue-squash Add this label to instruct the Commit Queue to squash all the PR commits into the first one. label Apr 2, 2026

Renegade334 reviewed Apr 2, 2026

View reviewed changes

Comment thread lib/internal/crypto/random.js Outdated

Comment thread lib/internal/crypto/random.js

Renegade334 reviewed Apr 2, 2026

View reviewed changes

Comment thread lib/internal/crypto/random.js

nabeel378 force-pushed the main branch from f702919 to a230870 Compare April 2, 2026 12:36

panva reviewed Apr 2, 2026

View reviewed changes

Comment thread doc/api/crypto.md Outdated

panva changed the title ~~crypto: add randomUUIDv7()~~ crypto: implement randomUUIDv7() Apr 2, 2026

nabeel378 force-pushed the main branch from a230870 to 80c0b4d Compare April 2, 2026 12:49

nabeel378 added 6 commits April 2, 2026 17:54

crypto: implement randomUUIDv7()

628715c

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

crypto: refactor randomUUIDv7() to use serializeUUID for improved rea…

274b11a

…dability

test: remove redundant checks for UUID version and variant bits

87dd2ac

crypto: update randomUUIDv7() to construct UUID string directly from …

828867d

…bytes

crypto: update randomUUIDv7() to accept options for disabling entropy…

e3a4a06

… cache

crypto: address review feedback for randomUUIDv7

8ddc406

- Make version/variant required params in serializeUUID - Share buffer pools (uuidData/uuidNotBuffered) between v4 and v7 Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

nabeel378 force-pushed the main branch from 80c0b4d to 8ddc406 Compare April 2, 2026 12:55

nabeel378 requested review from Renegade334 and panva April 2, 2026 13:15

jasnell approved these changes Apr 2, 2026

View reviewed changes

docs: update RFC 9562 link in crypto documentation

49dac43

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>

Renegade334 added the semver-minor PRs that contain new features and should be released in the next minor version. label Apr 2, 2026

panva approved these changes Apr 2, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

aduh95 force-pushed the main branch from 185f4a6 to 49dac43 Compare April 3, 2026 13:03

tniessen reviewed Apr 3, 2026

View reviewed changes

Renegade334 approved these changes Apr 4, 2026

View reviewed changes

panva added the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 5, 2026

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 5, 2026

nodejs-github-bot merged commit dec5973 into nodejs:main Apr 5, 2026
105 checks passed

nabeel378 mentioned this pull request Apr 5, 2026

doc: note non-monotonic clock in crypto.randomUUIDv7 #62600

Merged

araujogui mentioned this pull request Apr 5, 2026

crypto: add uuidv7 monotonic counter #62601

Open

theoludwig mentioned this pull request May 4, 2026

2026-05-05, Version 26.0.0 (Current) #62526

Merged

aduh95 mentioned this pull request May 5, 2026

2026-05-07, Version 26.1.0 #63137

Merged

Uh oh!

Conversation

nabeel378 commented Apr 2, 2026 • edited by Renegade334 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Apr 2, 2026

Uh oh!

Renegade334 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

panva commented Apr 2, 2026

Uh oh!

nabeel378 commented Apr 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

panva commented Apr 2, 2026

Uh oh!

This comment was marked as outdated.

aduh95 commented Apr 3, 2026

Uh oh!

nodejs-github-bot commented Apr 3, 2026

Uh oh!

nabeel378 commented Apr 3, 2026

Uh oh!

jasnell commented Apr 3, 2026

Uh oh!

nabeel378 commented Apr 3, 2026

Uh oh!

tniessen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nabeel378 commented Apr 4, 2026

Uh oh!

tniessen commented Apr 4, 2026

Uh oh!

Renegade334 commented Apr 4, 2026

Uh oh!

Uh oh!

nodejs-github-bot commented Apr 5, 2026

Uh oh!

panva commented Apr 5, 2026

Uh oh!

nabeel378 commented Apr 5, 2026

Uh oh!

theoludwig commented Apr 7, 2026

Uh oh!

nabeel378 commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

nabeel378 commented Apr 2, 2026 •

edited by Renegade334

Loading

tniessen left a comment •

edited

Loading