@sourceregistry/node-openssl

A lightweight, promise-based TypeScript wrapper for executing OpenSSL CLI commands directly from Node.js, with rich buffer enhancements and a fluent, proxy-powered API.

This library abstracts the openssl command-line tool into a clean, asynchronous interface, enabling seamless integration of common cryptographic operations such as key generation, certificate signing, hashing, and PEM parsing.

Installation

Install the package using npm:

npm install @sourceregistry/node-openssl
Copy

Note: Ensure openssl is installed and available in your system's PATH.

If you don't have OpenSSL installed, you have two options:

1. Compile and install from source (https://github.com/openssl/openssl/blob/master/INSTALL.md)
2. Install from a precompile binary (https://github.com/openssl/openssl/wiki/Binaries)

Usage

Getting Started

The primary interface is the openssl tagged template function, which allows you to run any OpenSSL command using natural syntax.

import {openssl} from '@sourceregistry/node-openssl';


async function main() {
    // Generate a 2048-bit RSA private key
    const key = await openssl`genpkey -algorithm RSA -outform PEM -pkeyopt rsa_keygen_bits:2048`.one();
    console.log('Private Key:\n', key.data);
    console.log('SHA-256:', key.sha256);

    // Generate a self-signed certificate
    const cert = await openssl`req -x509 -new -key ${key} -subj "/CN=localhost" -days 365 -outform PEM`.one();
    console.log('Certificate:\n', cert.data);
    console.log('Is Certificate Chain?', cert.isChain);
}

main().catch(console.error);
Copy

Working with Output Buffers

All command outputs are enhanced Buffer objects with metadata and utilities:

const output = await openssl`x509 -in cert.pem -noout -text`;

console.log(output.type);        // e.g., "CERTIFICATE"
console.log(output.mimeType);    // e.g., "application/x-pkcs7-crl"
console.log(output.sha1);        // Base64URL-encoded SHA-1
console.log(output.md5);         // Base64URL-encoded MD5
console.log(output.data);        // PEM body (without headers)

// Convert to Node.js crypto KeyObject
const publicKey = output.toObject(); // createPublicKey(output)
Copy

Accessing OpenSSL Version

console.log('OpenSSL Version:', openssl.version);
// { major: 3, minor: 0, patch: 2, release_date: '...'}
Copy

File I/O and Temporary Workdir

You can pass Buffer objects directly — they’re automatically written to temp files:

const csrBuffer = Buffer.from('...');
const signedCert = await openssl`x509 -req -CA ca.crt -CAkey ca.key -in <(echo "${csrBuffer}") -outform PEM`;
Copy

Files produced by OpenSSL (e.g., .crt, .pem) are automatically read and included in the output array.

API Overview

openssl...(Tagged Template)

Execute any OpenSSL command. Returns a Promise<OpenSSLBuffer[]>.

const outputs = await openssl`dgst -sha256 file.txt`;
Copy

.one()

Convenience method to get the first output buffer:

const cert = await openssl`req -newkey ...`.one();
Copy

OpenSSLBuffer

Enhanced Buffer with:

• .sha1, .sha256, .md5: Hashes (base64url-encoded)
• .data: PEM body (header/footer stripped)
• .type: PEM type (CERTIFICATE, PRIVATE KEY, etc.)
• .isChain: true if multiple certs in PEM
• .certificates: Array of full certificate blocks (if chain)
• .mimeType: Inferred MIME type
• .toObject(): Convert to crypto.KeyObject

Static Methods

• OpenSSL.exec(args): Low-level execution with array args
• OpenSSL.init(): Initialize and detect OpenSSL version (is run automatically when importing the library)
• OpenSSL.AnalysePEM(buffer): Parse PEM metadata
• OpenSSL.TransformBuffer(buffer): Enhance a Buffer

Development

Prerequisites

• Node.js (v22+ older might work)
• OpenSSL (installed and in PATH)

Scripts

• npm run build: Compile TypeScript to dist/
• npm run test: Run unit tests (if any)
• npm run lint: Lint code with ESLint

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

We aim to support all standard OpenSSL workflows with a clean, type-safe interface.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.