feat: completely factorize SubtleCrypto.generateKey() #2050

hkleungai · 2025-06-23T17:43:03Z

Opening this PR in favor of this comment from @Renegade334 in my another PR in DT repo.

Since https://nodejs.org/api/webcrypto.html#cryptokeyusages lists the usages in its own table, and it is closely aligned to the MDN reference in https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey, I believe it is possible to raise such change to @types/web as well.

Potentially we can do this to other methods in the key-usages table, but let's see how reviewers think about this change, then we may perform the refactoring incrementally in subsequent PRs.

Fallback signature is also updated, in favor of matching richer shape of possible Algorithm object.

github-actions · 2025-06-23T17:43:15Z

Thanks for the PR!

This section of the codebase is owned by @saschanaz - if they write a comment saying "LGTM" then it will be merged.

inputfiles/overridingTypes.jsonc

Renegade334 · 2025-07-02T20:04:49Z

inputfiles/overridingTypes.jsonc

+                                    "typeParameters": [
+                                        {
+                                            "name": "T",
+                                            "extends": "{ name: string }"
+                                        }
+                                    ],
+                                    "param": [
+                                        {
+                                            "name": "algorithm",
+                                            "overrideType": "string | T"
+                                        }
+                                    ],


Unnecessary generic?

I believe this generic is needed, or else the fallback signature will fail to capture poosibly-work algorithm object with extra attibutes other than name.

See https://tsplay.dev/N5oDdW.

No-one's raised any issues with AlgorithmIdentifier; this seems an arbitrary modification.

See https://tsplay.dev/Ndp9MN, in which the method call is taken from types/node/test/globals-non-dom.ts in DefinitelyTyped.

Without the use of generic, mismatched algorithm and keyUsages[] params would yield a confusing error, saying the code is violating the wrong overload.

But with the generic, such mismatch will pass and give Promise<CryptoKeyPair | CryptoKey>. It may not be the best way to typecheck, but I think this generic could help prevent certain possible breaking change.

I don't really understand – the whole point of this PR is that it breaks in this case?

The example provided is a mismatch with the accepted usages of the new HmacKeyGenParams signature, and is genuinely incorrect usage that would error at runtime. If we're going to provide a route for the new keyUsages constraints to be ignored anyway, then there's surely there's no real advantage to these changes?

(We can always modify that test – I suspect that the selection of keyUsages there was entirely arbitrary.)

I think you are right. I have repushed the PR to remove the generics.

saschanaz · 2026-01-08T22:31:47Z

Ok, enough procrastinating to review this...

I think this PR is incorrectly based on Node.js docs while it should be based on Web Cryptography spec. Node.js had some freedom to add more algorithms than Web Cryptography has.

Would be nice if this can be limited to what's listed in the spec.

Bashamega

I reviewed this quickly and added links to the relevant specs. It might be useful to also include those links as comments in the JSONC file for future reference.

I added one question as well, and left a comment about something that doesn’t appear to be covered by the spec.

I’m not familiar with cryptography, so I’d prefer not to make further changes until @saschanaz has reviewed and approved these updates.

Note: It would be preferable to migrate this to KDL now, since we’ll need to do so eventually. If you’re interested in handling the migration, you can refer to the WebGL KDL file for syntax guidance:
https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/main/inputfiles/patches/webgl.kdl

The SubtleCrypto migration should be largely similar to the WebGL one.

Bashamega · 2026-01-09T04:48:10Z

inputfiles/overridingTypes.jsonc

-                                "generateKey(algorithm: \"Ed25519\" | { name: \"Ed25519\" }, extractable: boolean, keyUsages: ReadonlyArray<\"sign\" | \"verify\">): Promise<CryptoKeyPair>",
-                                "generateKey(algorithm: RsaHashedKeyGenParams | EcKeyGenParams, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKeyPair>",
-                                "generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKey>"
+                                "generateKey(algorithm: RsaHashedKeyGenParams & { name: \"RSA-OAEP\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKeyPair>",


https://w3c.github.io/webcrypto/#rsa-oaep

Bashamega · 2026-01-09T04:50:10Z

inputfiles/overridingTypes.jsonc

-                                "generateKey(algorithm: RsaHashedKeyGenParams | EcKeyGenParams, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKeyPair>",
-                                "generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKey>"
+                                "generateKey(algorithm: RsaHashedKeyGenParams & { name: \"RSA-OAEP\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: (RsaHashedKeyGenParams & { name: \"RSA-PSS\" | \"RSASSA-PKCS1-v1_5\" }) | EcKeyGenParams | \"Ed25519\" | { name: \"Ed25519\" } | \"Ed448\" | { name: \"Ed448\" }, extractable: boolean, keyUsages: readonly (\"sign\" | \"verify\")[]): Promise<CryptoKeyPair>",


https://w3c.github.io/webcrypto/#rsa-pss
https://w3c.github.io/webcrypto/#rsassa-pkcs1

Bashamega · 2026-01-09T04:51:27Z

inputfiles/overridingTypes.jsonc

-                                "generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKey>"
+                                "generateKey(algorithm: RsaHashedKeyGenParams & { name: \"RSA-OAEP\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: (RsaHashedKeyGenParams & { name: \"RSA-PSS\" | \"RSASSA-PKCS1-v1_5\" }) | EcKeyGenParams | \"Ed25519\" | { name: \"Ed25519\" } | \"Ed448\" | { name: \"Ed448\" }, extractable: boolean, keyUsages: readonly (\"sign\" | \"verify\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: \"X25519\" | { name: \"X25519\" } | \"X448\" | { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",


https://w3c.github.io/webcrypto/#x25519

Bashamega · 2026-01-09T04:52:53Z

inputfiles/overridingTypes.jsonc

-                                "generateKey(algorithm: AesKeyGenParams | HmacKeyGenParams | Pbkdf2Params, extractable: boolean, keyUsages: ReadonlyArray<KeyUsage>): Promise<CryptoKey>"
+                                "generateKey(algorithm: RsaHashedKeyGenParams & { name: \"RSA-OAEP\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: (RsaHashedKeyGenParams & { name: \"RSA-PSS\" | \"RSASSA-PKCS1-v1_5\" }) | EcKeyGenParams | \"Ed25519\" | { name: \"Ed25519\" } | \"Ed448\" | { name: \"Ed448\" }, extractable: boolean, keyUsages: readonly (\"sign\" | \"verify\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: \"X25519\" | { name: \"X25519\" } | \"X448\" | { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",


Suggested change

"generateKey(algorithm: \"X25519\" | { name: \"X25519\" } | \"X448\" | { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",

"generateKey(algorithm: \"X25519\" | { name: \"X25519\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",

There is no mention of X448 in the specs

Bashamega · 2026-01-09T04:55:08Z

inputfiles/overridingTypes.jsonc

+                                "generateKey(algorithm: RsaHashedKeyGenParams & { name: \"RSA-OAEP\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: (RsaHashedKeyGenParams & { name: \"RSA-PSS\" | \"RSASSA-PKCS1-v1_5\" }) | EcKeyGenParams | \"Ed25519\" | { name: \"Ed25519\" } | \"Ed448\" | { name: \"Ed448\" }, extractable: boolean, keyUsages: readonly (\"sign\" | \"verify\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: \"X25519\" | { name: \"X25519\" } | \"X448\" | { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: AesKeyGenParams & { name: \"AES-CBC\" | \"AES-CTR\" | \"AES-GCM\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKey>",


https://w3c.github.io/webcrypto/#aes-cbc
https://w3c.github.io/webcrypto/#aes-ctr
https://w3c.github.io/webcrypto/#aes-gcm

Bashamega · 2026-01-09T04:55:40Z

inputfiles/overridingTypes.jsonc

+                                "generateKey(algorithm: (RsaHashedKeyGenParams & { name: \"RSA-PSS\" | \"RSASSA-PKCS1-v1_5\" }) | EcKeyGenParams | \"Ed25519\" | { name: \"Ed25519\" } | \"Ed448\" | { name: \"Ed448\" }, extractable: boolean, keyUsages: readonly (\"sign\" | \"verify\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: \"X25519\" | { name: \"X25519\" } | \"X448\" | { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" | \"deriveBits\")[]): Promise<CryptoKeyPair>",
+                                "generateKey(algorithm: AesKeyGenParams & { name: \"AES-CBC\" | \"AES-CTR\" | \"AES-GCM\" }, extractable: boolean, keyUsages: readonly (\"encrypt\" | \"decrypt\" | \"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKey>",
+                                "generateKey(algorithm: AesKeyGenParams & { name: \"AES-KW\" }, extractable: boolean, keyUsages: readonly (\"wrapKey\" | \"unwrapKey\")[]): Promise<CryptoKey>",


https://w3c.github.io/webcrypto/#aes-kw

Bashamega · 2026-01-09T05:02:13Z

baselines/webworker.generated.d.ts

+    generateKey(algorithm: (RsaHashedKeyGenParams & { name: "RSA-PSS" | "RSASSA-PKCS1-v1_5" }) | EcKeyGenParams | "Ed25519" | { name: "Ed25519" } | "Ed448" | { name: "Ed448" }, extractable: boolean, keyUsages: readonly ("sign" | "verify")[]): Promise<CryptoKeyPair>;
+    generateKey(algorithm: "X25519" | { name: "X25519" } | "X448" | { name: "X448" }, extractable: boolean, keyUsages: readonly ("deriveKey" | "deriveBits")[]): Promise<CryptoKeyPair>;
+    generateKey(algorithm: AesKeyGenParams & { name: "AES-CBC" | "AES-CTR" | "AES-GCM" }, extractable: boolean, keyUsages: readonly ("encrypt" | "decrypt" | "wrapKey" | "unwrapKey")[]): Promise<CryptoKey>;
+    generateKey(algorithm: AesKeyGenParams & { name: "AES-KW" }, extractable: boolean, keyUsages: readonly ("wrapKey" | "unwrapKey")[]): Promise<CryptoKey>;


I am not sure if you want to use AesKeyGenParams, it is not a type
https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/fbc37600c4f811a4b1ad56431a6a59d81c6161a8/baselines/webworker.generated.d.ts#L33C1-L35C2

Can you elaborate? How is it not a type?

Never mind, this is correct.

hkleungai · 2026-01-09T08:25:33Z

Thank you for your feedback.

It has been a while since I worked on this PR... I will need some time (maybe over the weekend) to digest the comments and the latest dev on this repo first. :)

Bashamega suggested changes Jun 24, 2025

View reviewed changes

inputfiles/overridingTypes.jsonc Outdated Show resolved Hide resolved

hkleungai force-pushed the crypto-factorize-subtle.generateKey branch from 53beb15 to 0dc3d22 Compare June 24, 2025 04:24

saschanaz mentioned this pull request Jun 30, 2025

Split addedTypes/overridingTypes/removedTypes by topics #2053

Open

Renegade334 reviewed Jul 2, 2025

View reviewed changes

feat: completely factorize SubtleCrypto.generateKey()

a6b6305

hkleungai force-pushed the crypto-factorize-subtle.generateKey branch from 0dc3d22 to a6b6305 Compare July 4, 2025 08:40

saschanaz mentioned this pull request Jan 8, 2026

Add X25519 generateKey overload to SubtleCrypto #2358

Merged

Bashamega reviewed Jan 9, 2026

View reviewed changes

	"generateKey(algorithm: \"X25519\" \| { name: \"X25519\" } \| \"X448\" \| { name: \"X448\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" \| \"deriveBits\")[]): Promise<CryptoKeyPair>",
	"generateKey(algorithm: \"X25519\" \| { name: \"X25519\" }, extractable: boolean, keyUsages: readonly (\"deriveKey\" \| \"deriveBits\")[]): Promise<CryptoKeyPair>",

feat: completely factorize SubtleCrypto.generateKey() #2050

Are you sure you want to change the base?

feat: completely factorize SubtleCrypto.generateKey() #2050

Uh oh!

Conversation

hkleungai commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jun 23, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saschanaz commented Jan 8, 2026

Uh oh!

Bashamega left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bashamega Jan 9, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hkleungai commented Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hkleungai commented Jun 23, 2025 •

edited

Loading

Bashamega Jan 9, 2026 •

edited

Loading