tiny-crypto-suite
Version:
Tiny tools, big crypto — seamless encryption and certificate handling for modern web and Node apps.
331 lines • 16.1 kB
text/typescript
export default TinyCertCrypto;
/**
* Class representing a certificate and key management utility.
*
* This class provides functionality to load, initialize, and manage X.509 certificates and RSA keys.
* It supports encryption and decryption operations using RSA keys, and also includes utility methods
* for certificate handling and metadata extraction.
*
* @class
*/
declare class TinyCertCrypto {
/**
* Constructs a new instance of TinyCertCrypto.
*
* This class provides cross-platform (Node.js and browser) support
* for handling X.509 certificates and performing RSA-based encryption and decryption.
*
* The constructor accepts optional paths or PEM buffers for the public certificate and private key.
* If used in a browser environment, either `publicCertPath` or `publicCertBuffer` is required.
*
* @param {Object} [options={}] - Initialization options.
* @param {string|null} [options.publicCertPath=null] - Path or URL to the public certificate in PEM format.
* @param {string|null} [options.privateKeyPath=null] - Path or URL to the private key in PEM format.
* @param {string|Buffer|null} [options.publicCertBuffer=null] - The public certificate as a PEM string or Buffer.
* @param {string|Buffer|null} [options.privateKeyBuffer=null] - The private key as a PEM string or Buffer.
* @param {EncryptionScheme} [options.cryptoType='RSA-OAEP'] - The algorithm identifier used with Crypto API.
*
* @throws {Error} If in a browser and neither `publicCertPath` nor `publicCertBuffer` is provided.
* @throws {Error} If provided buffers are not strings or Buffers.
*/
constructor({ publicCertPath, privateKeyPath, publicCertBuffer, privateKeyBuffer, cryptoType, }?: {
publicCertPath?: string | null | undefined;
privateKeyPath?: string | null | undefined;
publicCertBuffer?: string | Buffer<ArrayBufferLike> | null | undefined;
privateKeyBuffer?: string | Buffer<ArrayBufferLike> | null | undefined;
cryptoType?: import("node-forge").pki.rsa.EncryptionScheme | undefined;
});
/** @typedef {import('node-forge')} NodeForge */
/** @typedef {import('node-forge').pki.Certificate} Certificate */
/** @typedef {import('node-forge').pki.CertificateField} CertificateField */
/** @typedef {import('node-forge').pki.rsa.PublicKey} PublicKey */
/** @typedef {import('node-forge').pki.rsa.PrivateKey} PrivateKey */
/** @typedef {import('node-forge').pki.rsa.EncryptionScheme} EncryptionScheme */
/** @typedef {import('node-forge').pki.PEM} PEM */
/** @typedef {Record<string|number, any>|any[]} CryptoResult */
/** @typedef {string} Base64 */
/** @type {PublicKey|null} */ publicKey: import("node-forge").pki.rsa.PublicKey | null;
/** @type {PrivateKey|null} */ privateKey: import("node-forge").pki.rsa.PrivateKey | null;
/** @type {Certificate|null} */ publicCert: import("node-forge").pki.Certificate | null;
/** @type {Record<string, any>|null} */ metadata: Record<string, any> | null;
/** @type {string|null} */ source: string | null;
cryptoType: import("node-forge").pki.rsa.EncryptionScheme;
publicCertPath: string | null;
privateKeyPath: string | null;
publicCertBuffer: string | Buffer<ArrayBufferLike> | null;
privateKeyBuffer: string | Buffer<ArrayBufferLike> | null;
/**
* Starts the internal TinyCrypto instance.
* If an internal TinyCrypto instance is already set, an error will be thrown to prevent overriding it.
*
* @param {TinyCrypto} [tinyCrypto] - The TinyCrypto instance to be set.
* @throws {Error} Throws if TinyCrypto instance has already been set.
*/
startCrypto(tinyCrypto?: TinyCrypto): void;
/**
* Returns the previously loaded TinyCrypto instance.
* Assumes the module has already been loaded.
*
* @returns {TinyCrypto} The TinyCrypto module.
*/
getCrypto(): TinyCrypto;
/**
* Checks if the TinyCrypto instance exists.
*
* This method returns `true` if the TinyCrypto module has been set and is not null,
* otherwise returns `false`.
*
* @returns {boolean} Whether the TinyCrypto module exists.
*/
existsCrypto(): boolean;
/**
* Add a new value type and its converter function.
* @param {string} typeName
* @param {(data: any) => any} getFunction
* @param {(data: any) => { __type: string, value?: any }} convertFunction
*/
addValueType(typeName: string, getFunction: (data: any) => any, convertFunction: (data: any) => {
__type: string;
value?: any;
}): void;
/**
* Sets the deep serialization and deserialization mode in the TinyCrypto instance.
* If the argument is a boolean, updates the deep mode accordingly.
* Throws an error if the value is not a boolean.
*
* @param {boolean} value - A boolean indicating whether deep mode should be enabled.
* @throws {Error} Throws if the provided value is not a boolean.
*/
setDeepMode(value: boolean): void;
forge: typeof import("node-forge") | undefined;
/**
* Public wrapper for fetching the `node-forge` module.
* Useful for on-demand loading in environments like browsers.
*
* @returns {Promise<NodeForge>} The loaded `node-forge` module.
*/
fetchNodeForge(): Promise<typeof import("node-forge")>;
/**
* Public wrapper for accessing the `node-forge` instance.
*
* @returns {NodeForge} The `node-forge` module.
*/
getNodeForge(): typeof import("node-forge");
/**
* Generates a new X.509 certificate along with a public/private RSA key pair.
*
* This method can only be used in Node.js environments. It throws an error if a certificate
* or key is already loaded into the instance.
*
* @param {Object<string, string>} subjectFields - An object representing the subject fields of the certificate (e.g., CN, O, C).
* @param {Object} [options={}] - Optional configuration for key and certificate generation.
* @param {number} [options.modulusLength=2048] - Length of the RSA key in bits.
* @param {number} [options.validityInYears=1] - Number of years the certificate will be valid.
* @param {number} [options.randomBytesLength=16] - Number of random bytes to use for serial number generation.
*
* @returns {Promise<{publicKey: string, privateKey: string, cert: string}>} The generated keys and certificate in PEM format.
* @throws {Error} If running in a browser or if a cert/key is already loaded.
*/
generateX509Cert(subjectFields: {
[x: string]: string;
}, options?: {
modulusLength?: number | undefined;
validityInYears?: number | undefined;
randomBytesLength?: number | undefined;
}): Promise<{
publicKey: string;
privateKey: string;
cert: string;
}>;
/**
* Initializes the instance by loading the public certificate and, optionally, the private key.
*
* This method must be called before using cryptographic operations that depend on a loaded certificate.
* It supports both Node.js and browser environments.
*
* In Node.js:
* - It loads PEM data from provided file paths or buffers.
*
* In browsers:
* - It loads PEM data from provided URLs or ArrayBuffers.
*
* @async
* @throws {Error} If a certificate is already loaded.
* @throws {Error} If no public certificate is provided.
* @throws {Error} If the PEM type cannot be determined or is invalid.
*/
init(): Promise<void>;
/**
* Extracts the metadata of the loaded X.509 certificate.
*
* Returns an object containing the certificate's metadata such as the subject, issuer,
* serial number, and validity period. If no certificate is loaded, an empty object is returned.
*
* @returns {Record<string, any>} The metadata of the certificate, or an empty object if no certificate is loaded.
*/
extractCertMetadata(): Record<string, any>;
/**
* Encrypts a JSON object using the initialized public key.
*
* This method serializes the provided JSON object to a string and encrypts it using the
* public key in PEM format. The encryption is done using the algorithm defined in the
* `cryptoType` property (e.g., 'RSA-OAEP').
*
* @param {CryptoResult} jsonObject - The JSON object to be encrypted.
* @returns {Base64} The encrypted JSON object, encoded in Base64 format.
* @throws {Error} If the public key is not initialized (i.e., if `init()` or `generateKeyPair()` has not been called).
*/
encryptJson(jsonObject: any[] | Record<string | number, any>): string;
/**
* Decrypts a Base64-encoded encrypted JSON string using the initialized private key.
*
* This method takes the encrypted Base64 string, decodes it, and decrypts it using the
* private key in PEM format. It then parses the decrypted string back into a JSON object.
*
* @param {Base64} encryptedBase64 - The encrypted JSON string in Base64 format to be decrypted.
* @returns {CryptoResult} The decrypted JSON object.
* @throws {Error} If the private key is not initialized.
*/
decryptToJson(encryptedBase64: string): any[] | Record<string | number, any>;
/**
* @typedef {Object} EncryptedDataParamsNoKeys
* @property {Base64} auth - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
* @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
*/
/**
* @typedef {Object} EncryptedDataParams
* @property {Base64} auth - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
* @property {string} iv - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
* @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
* @property {string} authTag - The authentication tag used to verify the integrity of the encrypted data.
*/
/**
* Encrypts a value using the initialized public key.
*
* This method serializes the provided value to a string and encrypts it using the
* public key in PEM format. The encryption is done using the algorithm defined in the
* `cryptoType` property (e.g., 'RSA-OAEP').
*
* @param {*} data - The value to be encrypted.
* @returns {EncryptedDataParams} The encrypted value, encoded in Base64 format.
* @throws {Error} If the public key is not initialized (i.e., if `init()` or `generateKeyPair()` has not been called).
*/
encrypt(data: any): {
/**
* - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
*/
auth: string;
/**
* - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
*/
iv: string;
/**
* - The encrypted data to decrypt, encoded with the output encoding.
*/
encrypted: string;
/**
* - The authentication tag used to verify the integrity of the encrypted data.
*/
authTag: string;
};
/**
* Decrypts a Base64-encoded encrypted value using the initialized private key.
*
* This method takes the encrypted Base64 string, decodes it, and decrypts it using the
* private key in PEM format. It then parses the decrypted string back into a value.
*
* @param {EncryptedDataParams} params - The encrypted value in Base64 format to be decrypted.
* @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
* @returns {*} The decrypted value.
* @throws {Error} If the private key is not initialized.
*/
decrypt({ auth, iv, authTag, encrypted }: {
/**
* - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
*/
auth: string;
/**
* - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
*/
iv: string;
/**
* - The encrypted data to decrypt, encoded with the output encoding.
*/
encrypted: string;
/**
* - The authentication tag used to verify the integrity of the encrypted data.
*/
authTag: string;
}, expectedType?: string | null): any;
/**
* Encrypts a value using the initialized public key.
*
* This method serializes the provided value to a string and encrypts it using the
* public key in PEM format. The encryption is done using the algorithm defined in the
* `cryptoType` property (e.g., 'RSA-OAEP').
*
* @param {*} data - The value to be encrypted.
* @returns {EncryptedDataParamsNoKeys} The encrypted value, encoded in Base64 format.
* @throws {Error} If the public key is not initialized (i.e., if `init()` or `generateKeyPair()` has not been called).
*/
encryptWithoutKey(data: any): {
/**
* - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
*/
auth: string;
/**
* - The encrypted data to decrypt, encoded with the output encoding.
*/
encrypted: string;
};
/**
* Decrypts a Base64-encoded encrypted value using the initialized private key.
*
* This method takes the encrypted Base64 string, decodes it, and decrypts it using the
* private key in PEM format. It then parses the decrypted string back into a value.
*
* @param {EncryptedDataParamsNoKeys} params - The encrypted value in Base64 format to be decrypted.
* @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
* @returns {*} The decrypted value.
* @throws {Error} If the private key is not initialized.
*/
decryptWithoutKey({ auth, encrypted }: {
/**
* - The Initialization Vector (IV) encrypted by the TinyCertCrypto used in encryption, encoded with the output encoding.
*/
auth: string;
/**
* - The encrypted data to decrypt, encoded with the output encoding.
*/
encrypted: string;
}, expectedType?: string | null): any;
/**
* Checks if both the public and private keys are initialized.
*
* This method verifies if both the public key and private key have been initialized
* in the instance. It returns `true` if both keys are present, otherwise `false`.
*
* @returns {boolean} `true` if both public and private keys are initialized, `false` otherwise.
*/
hasKeys(): boolean;
/**
* Checks if a public certificate is initialized.
*
* This method checks if the public certificate has been loaded or initialized in the instance.
* It returns `true` if the public certificate is available, otherwise `false`.
*
* @returns {boolean} `true` if the public certificate is initialized, `false` otherwise.
*/
hasCert(): boolean;
/**
* Resets the instance by clearing the keys and certificate data.
*
* This method sets the public and private keys, the public certificate, metadata, and
* the source to `null`, effectively resetting the instance to its initial state.
*/
reset(): void;
#private;
}
import { Buffer } from 'buffer';
import TinyCrypto from './TinyCrypto.mjs';
//# sourceMappingURL=TinyCertCrypto.d.mts.map