Skip to content

doc: add cjs examples to webcrypto#62956

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

doc: add cjs examples to webcrypto#62956
mfdebian wants to merge 1 commit intonodejs: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
Copy link
Copy Markdown
Member

@lpinca lpinca left a comment

Choose a reason for hiding this comment

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

RSLGTM

Copy link
Copy Markdown
Member

@panva panva left a comment

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.

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