Skip to content

doc: add cjs examples to webcrypto#62956

Open
mfdebian wants to merge 1 commit into
nodejs:mainfrom
mfdebian:docs-webcrypto-cjs
Open

doc: add cjs examples to webcrypto#62956
mfdebian wants to merge 1 commit into
nodejs:mainfrom
mfdebian:docs-webcrypto-cjs

Conversation

@mfdebian

Copy link
Copy Markdown
Contributor

This PR adds the missing CJS examples to their respective counterparts for the Web Crypto API documentation.

Most examples were not printing anything back to users trying this examples, now all examples print back what they're creating.

Also, the Checking for runtime algorithm support example, at least on node v25.1.0, was throwing the error:

node:internal/crypto/webidl:680
              throw lazyDOMException(
                    ^

DOMException [OperationError]: AES-OCB algorithm.iv must be no more than 15 bytes
    at Object.validator (node:internal/crypto/webidl:680:21)
    at Object.AeadParams (node:internal/crypto/webidl:313:27)
    at normalizeAlgorithm (node:internal/crypto/util:566:61)
    at SubtleCrypto.encrypt (node:internal/crypto/webcrypto:1191:15)
    at file:///home/alpi/Documents/prjct/node/cjs-web-crypto-api/13originalSubtleAlgo.mjs:48:39

Node.js v25.1.0

The error comes from AES-OCB requiring an IV of at most 15 bytes, but we were always generating 16. The fix was to generate 15 bytes when AES-OCB is selected. But for that particular example I wasn't able to create a CJS counterpart since as of now I'm lacking the knowledge of how SubleCrypto behaves.

I've tested all examples included in this PR and they all work/behave as expected now.

Thanks again for everything!

@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/crypto

@nodejs-github-bot nodejs-github-bot added crypto Issues and PRs related to the crypto subsystem. doc Issues and PRs related to the documentations. labels Apr 25, 2026

@lpinca lpinca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

@panva panva left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mfdebian thank you. I don't find these proposed changes particularly helpful. Let's try and trim it down.

First, we don't need different/both cjs and ejs examples in webcrypto, there doesn't have to be a require() or import anywhere because crypto is available on the global scope, hence why the existing examples do const { subtle } = globalThis.crypto;. A single example is fine, and it's fine if it's just js because the way they're written they execute in any module type.

Therefore let's start off with the examples that we had and improve them incrementally instead.

@mfdebian

mfdebian commented Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

@panva Thank you for your feedback and sorry I took so long to respond, I'm more than happy to make the necessary changes and get this PR going. I think that as a starting point maybe I should leave only the fix for the example that is currently throwing an error and we can just merge that, what do you think?

Having said that, I do believe that examples from the docs should yield some output back to the users, and most of the current examples are pretty much silent or functions are not even being invoked, so users would need to grab a lot of extra context to make those examples work. For instance, for the Sign and verify example if I wanted to call one of the functions naively (as a learning student who's reading the docs for the first time might do) they'd just receive an error. At least this has been one my goals while updating the other sections of the documentation, to make it easier for people who're starting/learning to be able to just copy/paste the examples and learn while doing. I am inclined to say that maybe we can reach a middle ground in which we just update the current examples to yield some output, but then the docs already have a mixture or CJS and MJS examples, for instance, if a student (or generally speaking someone who's just starting and learning) runs the Checking for runtime algorithm support on a CJS codebase they would just receive an error, and I think the docs should not yield errors whatsoever.

But again, I'm super open to feedback and I'm more than happy to help in any way I can to make the docs better, so let me know what you think! And again, sorry for the delay in the response and thank you for taking the time in reviewing the changes and give feedback, it's very much appreciated! 🤗

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

crypto Issues and PRs related to the crypto subsystem. doc Issues and PRs related to the documentations.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants