easy-ocsp/dist/index.d.ts

An easy-to-use OCSP client for Node.js

import { X509Certificate } from 'node:crypto';
import * as pkijs from 'pkijs';

/**
 * Convert a certificate to a pkijs.Certificate object
 * @param cert The certificate to convert as a string, Buffer, X509Certificate or pkijs.Certificate
 * @returns A pkijs.Certificate object
 */
declare function convertToPkijsCert(cert: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer): pkijs.Certificate;
/**
 * Convert a pkijs.Certificate object to a PEM encoded X.509 certificate
 * @param cert The certificate to convert
 * @returns The certificate as a PEM encoded string
 */
declare function convertPkijsCertToPem(cert: pkijs.Certificate): string;

/**
 * Parse a raw OCSP response and return the status of the certificate.
 * @param responseData The raw OCSP response data as a Buffer.
 * @param certificate The certificate to check the status for.
 * @param issuerCertificate The issuer certificate of the certificate to check.
 * @param config Additional configuration options, see {@link OCSPStatusConfig}.
 * @param nonce The nonce used in the OCSP request.
 * @returns The parsed OCSP response.
 */
declare function parseOCSPResponse(responseData: ArrayBuffer, certificate: pkijs.Certificate, issuerCertificate: pkijs.Certificate, config: OCSPStatusConfig, nonce: ArrayBuffer | null): Promise<OCSPStatusResponse>;

/**
 * Get a TLS certificate by hostname. This function will always connect to port 443.
 * @param hostname Hostname to connect to (e.g. 'github.com') - not an URL
 * @param timeout Timeout in milliseconds (default: 6000)
 * @returns Buffer containing the raw certificate (DER)
 * @throws AbortError if the request timed out
 */
declare function downloadCert(hostname: string, timeout?: number): Promise<Buffer>;

/**
 * Additional optional configuration
 */
type OCSPStatusConfig = {
    /**
     * The issuer certificate authority. If not provided, it will be downloaded from the issuer URL. If you already have the issuer certificate, you can provide it here to improve performance.
     */
    ca?: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer;
    /**
     * The URL of the OCSP responder. By default, it will be extracted from the certificate. If you already know the OCSP responder URL, you can provide it here.
     */
    ocspUrl?: string;
    /**
     * The OCSP responder certificate to validate the signature of the OCSP response. If not provided issuer certificate will be used.
     */
    ocspCertificate?: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer;
    /**
     * Whether to validate the signature of the OCSP response. This is enabled by default and should only be disabled for debugging purposes.
     * @defaultValue true
     */
    validateSignature?: boolean;
    /**
     * Timeout in milliseconds for the OCSP request and download of the issuer certificate. If the request takes longer than this, it will be aborted.
     * @defaultValue 6000
     */
    timeout?: number;
    /**
     * Whether to include a nonce in the OCSP request. This is enabled by default because it enhances security.
     * @defaultValue true
     */
    enableNonce?: boolean;
    /**
     * Whether to return the raw response as a buffer additionally to the parsed response. This is disabled by default.
     */
    rawResponse?: boolean;
};
/**
 * The reason why a certificate was revoked.
 * https://www.rfc-editor.org/rfc/rfc5280#section-5.3.1
 */
declare enum OCSPRevocationReason {
    unspecified = 0,
    keyCompromise = 1,
    caCompromise = 2,
    affiliationChanged = 3,
    superseded = 4,
    cessationOfOperation = 5,
    certificateHold = 6,
    removeFromCRL = 8,
    privilegeWithdrawn = 9,
    aACompromise = 10
}
type OCSPStatusResponse = {
    /**
     * Revocation status of the certificate
     */
    status: 'good' | 'revoked' | 'unknown';
    /**
     * The OCSP responder URL
     */
    ocspUrl: string;
    /**
     * Time when the certificate was revoked. Only and not always available if the status is 'revoked'.
     */
    revocationTime?: Date;
    /**
     * The time at or before which newer information will be available about the status of the certificate.
     */
    nextUpdate?: Date;
    /**
     * The most recent time at which the status being indicated is known by the responder to have been correct.
     */
    thisUpdate?: Date;
    /**
     * The time at which the response was produced.
     */
    producedAt?: Date;
    /**
     * The revocation reason. Only available if the status is 'revoked' and the OCSP response contains a revocation reason.
     */
    revocationReason?: OCSPRevocationReason;
    /**
     * The raw OCSP response as a buffer. Only available if the rawResponse option is enabled in the config.
     */
    rawResponse?: Buffer;
};

/**
 * Function to download and parse the certificate of the issuer of a certificate
 * This function is used internally to download the issuer certificate if it is not provided in the config
 * Its exported for convenience if you want to download the issuer certificate manually for some reason
 * @param cert The certificate to download the issuer certificate for, can be a PEM encoded string, X509Certificate object, pkijs.Certificate or the raw certificate as Buffer or ArrayBuffer
 * @param timeout Optional timeout in milliseconds for the request. Default is 6000ms
 * @returns A pkijs.Certificate object of the issuer certificate
 */
declare function downloadIssuerCert(cert: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer, timeout?: number): Promise<pkijs.Certificate>;
/**
 * Get the revocation status of a certificate.
 * @param cert The certificate to check, as PEM encoded string, X509Certificate object, pkijs.Certificate or the raw certificate as Buffer or ArrayBuffer
 * @param config Provide optional additional configuration
 * @returns Revocation status of the certificate and additional information if available
 * @throws Error if the OCSP request failed
 * @throws AbortError if the request timed out
 */
declare function getCertStatus(cert: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer, config?: OCSPStatusConfig): Promise<OCSPStatusResponse>;
/**
 * Download the tls certificate that is used for a domain and check its revocation status. This is a convenience function that combines downloadCert and getCertStatus
 * @param domain Domain to check the certificate for (e.g. 'github.com')
 * @param config Provide optional additional configuration
 * @returns Revocation status of the certificate and additional information if available
 * @throws Error if the certificate could not be retrieved or the OCSP request failed
 * @throws AbortError if the request timed out
 */
declare function getCertStatusByDomain(domain: string, config?: OCSPStatusConfig): Promise<OCSPStatusResponse>;
/**
 * Get raw (binary) OCSP response for a certificate
 * The response is not parsed or validated.
 * @param cert The certificate to check, as PEM encoded string, X509Certificate object, pkijs.Certificate or the raw certificate as Buffer or ArrayBuffer
 * @param config Provide optional additional configuration
 * @returns The raw OCSP response as a buffer, the nonce and the pem encoded issuer certificate
 */
declare function getRawOCSPResponse(cert: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer, config?: OCSPStatusConfig): Promise<{
    rawResponse: Buffer<ArrayBuffer>;
    nonce: Buffer<ArrayBuffer> | undefined;
    issuerCert: string;
}>;
/**
 * Get the OCSP and issuer URLs from a certificate
 * @param cert The certificate to check, as PEM encoded string, X509Certificate object, pkijs.Certificate or the raw certificate as Buffer or ArrayBuffer
 * @returns OCSP and issuer URLs
 * @throws Error if the certificate does not contain the required information
 */
declare function getCertURLs(cert: string | Buffer | X509Certificate | pkijs.Certificate | ArrayBuffer): {
    ocspUrl: string;
    issuerUrl: string;
};

export { OCSPRevocationReason, type OCSPStatusConfig, type OCSPStatusResponse, convertPkijsCertToPem, convertToPkijsCert, downloadCert, downloadIssuerCert, getCertStatus, getCertStatusByDomain, getCertURLs, getRawOCSPResponse, parseOCSPResponse };