crypto: alias webcrypto.subtle and webcrypto.getRandomValues on crypto

[jasnell]

The aliases allow code written to assume that crypto.subtle and
crypto.getRandomValues() exist on the crypto global to just work.

Signed-off-by: James M Snell jasnell@gmail.com

[nodejs-github-bot]

Review requested:

• @nodejs/crypto

[panva]

code written to assume that [...]

A code like that will likely expect crypto to be on a globalThis, window, global, or similar in the first place. Nevertheless, I don't mind this change if it means some libraries will work.

It's worth pointing out that webcrypto is still experimental and there's no runtime warning about it being so.

[jasnell]

A code like that will likely expect crypto to be on a globalThis

Yep once this lands, I plan to open a PR to expose crypto on globalThis

[nodejs-github-bot]

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

[tniessen]

A code like that will likely expect crypto to be on a globalThis

Yep once this lands, I plan to open a PR to expose crypto on globalThis

What is the plan for doing that? I am unsure if this change makes sense without exposing crypto as a global. Otherwise, users still need to require or import crypto, which means that it remains incompatible with code that targets browsers etc., and not much is gained from these convenience additions.

Would the global crypto be equivalent to require('crypto') or would it be require('crypto').webcrypto? Based on this PR, I'd assume it would be the crypto module, which seems inconsistent with other environments.

[aduh95]

Otherwise, users still need to require or import crypto, which means that it remains incompatible with code that targets browsers etc., and not much is gained from these convenience additions.

Not exactly incompatible, thanks to import maps:

<script type="importmap">
  {
      "imports": {
          "node:crypto": "data:text/javascript,export%20default%20globalThis.crypto"
      }
  }
</script>
<script type="module">import crypto from 'node:crypto'; console.log(crypto.subtle);</script>

[tniessen]

@aduh95 I don't see how that helps. In browsers, there is already a crypto property attached to globalThis, and if users are intentionally using node:crypto (as in your example), then they can already import webcrypto from there and don't need this PR.

[jasnell]

Would the global crypto be equivalent to require('crypto') or would it be require('crypto').webcrypto? Based on this PR, I'd assume it would be the crypto module, which seems inconsistent with other environments.

It would be require('crypto'), which, yes, is a bit inconsistent with browser environments but ideally in a way that "ain't that bad". Importantly, with the combination of that and this pr, references like crypto.subtle and crypto.randomUUID() and crypto.getRandomValues() should just work even if the rest of the API is not consistent with browsers. It's the closest we can likely get to being consistent.

[nodejs-github-bot]

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

[dnalborczyk]

Would the global crypto be equivalent to require('crypto') or would it be require('crypto').webcrypto? Based on this PR, I'd assume it would be the crypto module, which seems inconsistent with other environments.

It would be require('crypto'), which, yes, is a bit inconsistent with browser environments but ideally in a way that "ain't that bad". Importantly, with the combination of that and this pr, references like crypto.subtle and crypto.randomUUID() and crypto.getRandomValues() should just work even if the rest of the API is not consistent with browsers. It's the closest we can likely get to being consistent.

why don't we put webcrypto (as crypto) on the global object? that would make more sense I think. that would be also consistent with browsers?

[dnalborczyk]

@jasnell one thing I'm curious about:

let webcrypto;
function lazyWebCrypto() {
  webcrypto ??= require('internal/crypto/webcrypto');
  return webcrypto;
}

does require not just use the cache as well and return the exact same thing (instance) in this case? meaning, is this not pretty much the same, even from a performance standpoint:

function lazyWebCrypto() {
  return require('internal/crypto/webcrypto');
}

[tniessen]

It would be require('crypto')

My concern is that

globalThis.crypto === require('crypto')

implies

globalThis.crypto !== require('crypto').webcrypto

unless

require('crypto') === require('crypto').webcrypto

which has implications such as

globalThis.crypto.constructor.name === 'Object'
globalThis.crypto.webcrypto.constructor.name === 'Crypto'

I get that we want to improve compatibility with code that uses web APIs, even if those weren't designed for Node.js, but exposing non-standard features through the standard globalThis.crypto API might add to the confusion and code that exclusively uses globalThis.crypto might work in Node.js, but not in a browser that supports Web Crypto.

Conversely, we could expose only Web Crypto as globalThis.crypto, but that would suggest that we consider Web Crypto to be the better alternative, which I am not sure we should at this point.

[jasnell]

@dnalborczyk:

why don't we put webcrypto (as crypto) on the global object? that would make more sense I think. that would be also consistent with browsers?

We can't really. That would create an inconsistency with the Node.js REPL where crypto (from require('crypto')) is available globally.

@tniessen:

I get that we want to improve compatibility with code that uses web APIs, even if those weren't designed for Node.js, but exposing non-standard features through the standard globalThis.crypto API might add to the confusion and code that exclusively uses globalThis.crypto might work in Node.js, but not in a browser that supports Web Crypto.

Yes, there's a small risk there but I think it's manageable and I think the benefits here outweigh the risks. You are right, tho, the risks are non-zero.

[jasnell]

@tniessen ... I just want to clarify, is your concern here blocking or can this PR go ahead and land?

[tniessen]

I just want to clarify, is your concern here blocking or can this PR go ahead and land?

It's not blocking :) I haven't given this enough thought one way or the other to have an opinion here, I'm just wary of convenience changes with potentially significant API implications.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/41266
✔  Done loading data for nodejs/node/pull/41266
----------------------------------- PR info ------------------------------------
Title      crypto: alias webcrypto.subtle and webcrypto.getRandomValues on crypto (#41266)
Author     James M Snell  (@jasnell)
Branch     jasnell:webcrypto-aliases -> nodejs:master
Labels     crypto, semver-minor, author ready, needs-ci, webcrypto, commit-queue-squash
Commits    3
 - crypto: alias webcrypto.subtle and webcrypto.getRandomValues on crypto
 - [Squash] nits
 - [Squash] nit
Committers 2
 - James M Snell 
 - GitHub 
PR-URL: https://github.com/nodejs/node/pull/41266
Reviewed-By: Filip Skokan 
Reviewed-By: Michaël Zasso 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/41266
Reviewed-By: Filip Skokan 
Reviewed-By: Michaël Zasso 
--------------------------------------------------------------------------------
   ⚠  Commits were pushed since the last review:
   ⚠  - [Squash] nit
   ℹ  This PR was created on Tue, 21 Dec 2021 18:40:38 GMT
   ✔  Approvals: 2
   ✔  - Filip Skokan (@panva): https://github.com/nodejs/node/pull/41266#pullrequestreview-837777172
   ✔  - Michaël Zasso (@targos) (TSC): https://github.com/nodejs/node/pull/41266#pullrequestreview-838130176
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2021-12-23T01:16:25Z: https://ci.nodejs.org/job/node-test-pull-request/41621/
- Querying data for job/node-test-pull-request/41621/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/1627255427

[nodejs-github-bot]

Landed in 353532b

[aduh95]

I don't think the getRandomValues shortcut should land on LTS given #41760. We should probably mark them as experimental given the whole WebCrypto API is itself experimental.
Adding backport-requested label in case you think it's still worth it to have SubtleCrypto shortcut and want to backport that.