From bfd490092ca1fac5cf2fe31d610c7efce9e22b8a Mon Sep 17 00:00:00 2001 From: Rob Hogan Date: Wed, 31 Dec 2025 13:37:35 -0800 Subject: [PATCH] Align Flow lib defs for Node.js crypto with v24 Summary: This is an AI-assisted change to align the Flow definitions for the `crypto` module with the Node.js docs as at v24. **New v24 APIs:** 1. **`hash(algorithm, data, [outputEncoding])`** - One-shot hashing convenience function - Added in Node.js v21.7.0, v20.12.0 - https://nodejs.org/api/crypto.html#cryptohashalgorithm-data-outputencoding 2. **X509Certificate new properties** (added in v22.10.0): - `validFromDate` - Certificate valid-from as Date object - `validToDate` - Certificate valid-to as Date object - https://nodejs.org/api/crypto.html#x509certificatevalidfromdate - https://nodejs.org/api/crypto.html#x509certificatevalidtodate **New Classes:** 3. **KeyObject** - Represents cryptographic keys (symmetric/asymmetric) - Properties: `type`, `asymmetricKeyType`, `asymmetricKeySize`, `symmetricKeySize` - Methods: `export()`, `equals()` - https://nodejs.org/api/crypto.html#class-keyobject 4. **X509Certificate** - X.509 certificate handling - Properties: `ca`, `fingerprint*`, `issuer`, `subject`, `publicKey`, `raw`, etc. - Methods: `checkEmail()`, `checkHost()`, `checkIP()`, `verify()`, etc. - https://nodejs.org/api/crypto.html#class-x509certificate 5. **Certificate** - Legacy SPKAC (Signed Public Key and Challenge) support - Static methods: `exportChallenge()`, `exportPublicKey()`, `verifySpkac()` - https://nodejs.org/api/crypto.html#class-certificate **Key Management Functions:** 6. **Key Creation:** - `createSecretKey(key, [encoding])` - Create symmetric KeyObject - `createPublicKey(key)` - Create public KeyObject - `createPrivateKey(key)` - Create private KeyObject - https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding - https://nodejs.org/api/crypto.html#cryptocreatepublickeykey - https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey 7. **Key Generation:** - `generateKeyPair()` / `generateKeyPairSync()` - Generate asymmetric key pairs - `generateKey()` / `generateKeySync()` - Generate symmetric keys - Supports: RSA, RSA-PSS, DSA, EC, Ed25519, Ed448, X25519, X448 - https://nodejs.org/api/crypto.html#cryptogeneratekeypairtype-options-callback - https://nodejs.org/api/crypto.html#cryptogeneratekeytype-options-callback 8. **Primality Testing:** - `checkPrime()` / `checkPrimeSync()` - Test if candidate is prime - https://nodejs.org/api/crypto.html#cryptocheckprimecandidate-options-callback **Other Improvements:** 9. **Hash.copy()** - Create deep copy of Hash object - https://nodejs.org/api/crypto.html#hashcopyoptions 10. **webcrypto property** - References web Crypto type - Web Crypto API types are NOT redefined (use existing definitions where available) - https://nodejs.org/api/webcrypto.html **Type Safety:** - All options objects use modern `Readonly<{...}>` syntax for inputs - Exact-by-default types throughout - Proper overloading for functions with optional parameters **References:** - Node.js crypto module docs: https://nodejs.org/api/crypto.html - Node.js Web Crypto API: https://nodejs.org/api/webcrypto.html Changelog: [Internal] --- > Generated by [Confucius Code Assist (CCA)](https://www.internalfb.com/wiki/Confucius/Analect/Shared_Analects/Confucius_Code_Assist_(CCA)/) [Confucius Session](https://www.internalfb.com/confucius?host=devvm45708.cln0.facebook.com&port=8086&tab=Chat&session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&entry_name=Code+Assist), [Trace](https://www.internalfb.com/confucius?session_id=1a3aa26e-e5a9-11f0-8d47-71a4a90f0494&tab=Trace) Reviewed By: vzaidman Differential Revision: D89934145 --- flow-typed/environment/node.js | 151 +++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) diff --git a/flow-typed/environment/node.js b/flow-typed/environment/node.js index 4527c7c39077..3cdff5ac61f3 100644 --- a/flow-typed/environment/node.js +++ b/flow-typed/environment/node.js @@ -603,6 +603,7 @@ declare class crypto$Hash extends stream$Duplex { data: string | Buffer, input_encoding?: 'utf8' | 'ascii' | 'latin1' | 'binary', ): crypto$Hash; + copy(options?: mixed): crypto$Hash; } declare class crypto$Hmac extends stream$Duplex { @@ -661,6 +662,83 @@ type crypto$key = ... }; +declare class crypto$KeyObject { + +asymmetricKeyType?: + | 'rsa' + | 'rsa-pss' + | 'dsa' + | 'ec' + | 'ed25519' + | 'ed448' + | 'x25519' + | 'x448'; + +asymmetricKeySize?: number; + +symmetricKeySize?: number; + +type: 'secret' | 'public' | 'private'; + + export( + options: Readonly<{ + type: 'pkcs1' | 'spki' | 'pkcs8' | 'sec1', + format: 'pem', + }>, + ): string; + export( + options: Readonly<{ + type: 'pkcs1' | 'spki' | 'pkcs8' | 'sec1', + format: 'der', + }>, + ): Buffer; + export(options: Readonly<{format: 'jwk'}>): mixed; + equals(otherKeyObject: crypto$KeyObject): boolean; +} + +declare class crypto$X509Certificate { + constructor(buffer: string | Buffer | $TypedArray | DataView): void; + + +ca: boolean; + +fingerprint: string; + +fingerprint256: string; + +fingerprint512: string; + +issuer: string; + +issuerCertificate?: crypto$X509Certificate; + +keyUsage: Array; + +publicKey: crypto$KeyObject; + +raw: Buffer; + +serialNumber: string; + +subject: string; + +subjectAltName: string; + +validFrom: string; + +validTo: string; + +validFromDate: Date; + +validToDate: Date; + + checkEmail( + email: string, + options?: Readonly<{subject?: 'always' | 'default' | 'never'}>, + ): string | void; + checkHost( + name: string, + options?: Readonly<{subject?: 'always' | 'default' | 'never'}>, + ): string | void; + checkIP(ip: string): string | void; + checkIssued(otherCert: crypto$X509Certificate): boolean; + checkPrivateKey(privateKey: crypto$KeyObject): boolean; + toJSON(): string; + toLegacyObject(): mixed; + toString(): string; + verify(publicKey: crypto$KeyObject): boolean; +} + +declare class crypto$Certificate { + static exportChallenge( + spkac: string | Buffer | $TypedArray | DataView, + ): Buffer; + static exportPublicKey( + spkac: string | Buffer | $TypedArray | DataView, + ): Buffer; + static verifySpkac(spkac: Buffer | $TypedArray | DataView): boolean; +} + declare module 'crypto' { declare var DEFAULT_ENCODING: string; @@ -820,6 +898,79 @@ declare module 'crypto' { a: Buffer | $TypedArray | DataView, b: Buffer | $TypedArray | DataView, ): boolean; + declare function hash( + algorithm: string, + data: string | Buffer | $TypedArray | DataView, + ): Buffer; + declare function hash( + algorithm: string, + data: string | Buffer | $TypedArray | DataView, + outputEncoding: buffer$Encoding, + ): string; + declare function createSecretKey( + key: Buffer | $TypedArray | DataView, + ): crypto$KeyObject; + declare function createSecretKey( + key: string, + encoding: buffer$Encoding, + ): crypto$KeyObject; + declare function createPublicKey( + key: string | Buffer | crypto$KeyObject | mixed, + ): crypto$KeyObject; + declare function createPrivateKey( + key: string | Buffer | mixed, + ): crypto$KeyObject; + declare function generateKeyPair( + type: + | 'rsa' + | 'rsa-pss' + | 'dsa' + | 'ec' + | 'ed25519' + | 'ed448' + | 'x25519' + | 'x448', + options: mixed, + callback: ( + err: ?Error, + publicKey: crypto$KeyObject, + privateKey: crypto$KeyObject, + ) => void, + ): void; + declare function generateKeyPairSync( + type: + | 'rsa' + | 'rsa-pss' + | 'dsa' + | 'ec' + | 'ed25519' + | 'ed448' + | 'x25519' + | 'x448', + options: mixed, + ): {publicKey: crypto$KeyObject, privateKey: crypto$KeyObject, ...}; + declare function generateKey( + type: 'hmac' | 'aes', + options: Readonly<{length: number}>, + callback: (err: ?Error, key: crypto$KeyObject) => void, + ): void; + declare function generateKeySync( + type: 'hmac' | 'aes', + options: Readonly<{length: number}>, + ): crypto$KeyObject; + declare function checkPrime( + candidate: Buffer | $TypedArray | DataView | bigint, + options?: Readonly<{checks?: number}>, + callback: (err: ?Error, result: boolean) => void, + ): void; + declare function checkPrimeSync( + candidate: Buffer | $TypedArray | DataView | bigint, + options?: Readonly<{checks?: number}>, + ): boolean; + declare class Certificate extends crypto$Certificate {} + declare class X509Certificate extends crypto$X509Certificate {} + declare class KeyObject extends crypto$KeyObject {} + declare var webcrypto: unknown; } type net$Socket$address = {