node-opcua-pki 6.19.1 → 6.21.0

package/dist/core-C6faZClF.d.mts

@@ -0,0 +1,1032 @@
+import { SubjectOptions, PrivateKey, CertificatePurpose, Subject, CaSigner } from 'node-opcua-crypto';
+
+/** RSA key size in bits. */
+type KeySize = 1024 | 2048 | 3072 | 4096;
+/** Hex-encoded SHA-1 certificate thumbprint. */
+type Thumbprint = string;
+/** A filesystem path to a file. */
+type Filename = string;
+/** Status of a certificate in the trust store. */
+type CertificateStatus = "unknown" | "trusted" | "rejected";
+
+/**
+ * @deprecated Use {@link KeySize} instead.
+ */
+type KeyLength = 1024 | 2048 | 3072 | 4096;
+declare function quote(str?: string): string;
+/**
+ * Subject Alternative Name (SAN) parameters for certificate
+ * generation.
+ */
+interface ProcessAltNamesParam {
+    /** DNS host names to include in the SAN extension. */
+    dns?: string[];
+    /** IP addresses to include in the SAN extension. */
+    ip?: string[];
+    /** OPC UA application URI for the SAN extension. */
+    applicationUri?: string;
+}
+/**
+ * Options for creating a Certificate Signing Request (CSR).
+ */
+interface CreateCertificateSigningRequestOptions extends ProcessAltNamesParam {
+    /** X.500 subject for the certificate. */
+    subject?: SubjectOptions | string;
+}
+/**
+ * Extended CSR options that include filesystem paths and
+ * certificate purpose — used internally by the OpenSSL toolbox.
+ */
+interface CreateCertificateSigningRequestWithConfigOptions extends CreateCertificateSigningRequestOptions {
+    /** Root directory of the PKI store. */
+    rootDir: Filename;
+    /** Path to the OpenSSL configuration file. */
+    configFile: Filename;
+    /**
+     * The private key: either a filesystem path to a PEM file (unencrypted;
+     * the historical behavior), or an already-resolved in-memory
+     * {@link PrivateKey} — see {@link CreateSelfSignCertificateWithConfigParam.privateKey}.
+     */
+    privateKey: Filename | PrivateKey;
+    /** Intended purpose of the certificate. */
+    purpose: CertificatePurpose;
+}
+/**
+ * Validity period parameters for certificate generation.
+ */
+interface StartDateEndDateParam {
+    /** Certificate "Not Before" date. Defaults to now. */
+    startDate?: Date;
+    /** Certificate "Not After" date (computed from validity). */
+    endDate?: Date;
+    /** Number of days the certificate is valid. @defaultValue 365 */
+    validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (X.509 supports second precision per RFC 5280
+     * §4.1.2.5; OpenSSL is invoked with `-startdate`/`-enddate` already).
+     *
+     * Typical use is short-lived certificates for demos or for renewal
+     * cycle testing. Existing day-based callers are unaffected.
+     */
+    validityMs?: number;
+}
+/**
+ * Parameters for creating a self-signed certificate.
+ */
+interface CreateSelfSignCertificateParam extends ProcessAltNamesParam, StartDateEndDateParam {
+    /** X.500 subject for the certificate. */
+    subject?: SubjectOptions | string;
+}
+/**
+ * Extended self-signed certificate options that include
+ * filesystem paths and purpose — used internally.
+ */
+interface CreateSelfSignCertificateWithConfigParam extends CreateSelfSignCertificateParam {
+    /** Root directory of the PKI store. */
+    rootDir: Filename;
+    /** Path to the OpenSSL configuration file. */
+    configFile: Filename;
+    /**
+     * The private key: either a filesystem path to a PEM file (unencrypted;
+     * the historical behavior), or an already-resolved in-memory
+     * {@link PrivateKey} — used when the key is passphrase-protected on
+     * disk, so the decrypted key material is never written back out in
+     * cleartext.
+     */
+    privateKey: Filename | PrivateKey;
+    /** Intended purpose of the certificate. */
+    purpose: CertificatePurpose;
+}
+/**
+ * A passphrase, or a function resolving one — called lazily, and at most
+ * once per `CertificateManager` / `CertificateAuthority` instance (the
+ * result is cached in memory). Never logged.
+ */
+type PrivateKeyPassphrase = string | (() => Promise<string>);
+/**
+ * Sources a {@link PrivateKey} from somewhere other than the local
+ * filesystem (an HSM, a KMS, ...). When configured on `CertificateManager`,
+ * it overrides disk entirely — the on-disk `own/private/private_key.pem` is
+ * neither generated nor read. `CertificateAuthority` does not support a
+ * provider (its signing paths are openssl reading a key file); it does
+ * support `privateKeyPassphrase`.
+ */
+interface PrivateKeyProvider {
+    getPrivateKey(): Promise<PrivateKey>;
+}
+/** Resolve a {@link PrivateKeyPassphrase}, if configured. */
+declare function resolvePrivateKeyPassphrase(passphrase: PrivateKeyPassphrase | undefined): Promise<string | undefined>;
+/**
+ * General-purpose parameters passed to CA operations such as
+ * {@link CertificateAuthority.signCertificateRequest} and
+ * {@link CertificateAuthority.revokeCertificate}.
+ */
+interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
+    /** X.500 subject for the certificate. */
+    subject?: SubjectOptions | string;
+    /** Path to the private key file. */
+    privateKey?: string;
+    /** Path to the OpenSSL configuration file. */
+    configFile?: string;
+    /** Root directory of the PKI store. */
+    rootDir?: string;
+    /** Output filename for the generated certificate. */
+    outputFile?: string;
+    /** CRL revocation reason (e.g. `"keyCompromise"`). */
+    reason?: string;
+}
+declare function adjustDate(params: StartDateEndDateParam): void;
+declare function adjustApplicationUri(params: Params): void;
+
+/**
+ * A record from the OpenSSL CA certificate database (`index.txt`).
+ */
+interface IssuedCertificateRecord {
+    /** Hex-encoded serial number (e.g. `"1000"`). */
+    serial: string;
+    /** Certificate status. */
+    status: "valid" | "revoked" | "expired";
+    /** X.500 subject string (slash-delimited). */
+    subject: string;
+    /** Certificate expiry date as ISO-8601 string. */
+    expiryDate: string;
+    /**
+     * Revocation date as ISO-8601 string.
+     * Only present when `status === "revoked"`.
+     */
+    revocationDate?: string;
+    /**
+     * CRL revocation reason (e.g. `"keyCompromise"`), as stored after the
+     * comma in the revocation-date field. Only present when
+     * `status === "revoked"` and a reason was recorded.
+     */
+    reason?: string;
+}
+/**
+ * Read and write access to a CA's OpenSSL-format certificate database
+ * (`index.txt`, `serial`, `crlnumber`, `certs/<SERIAL>.pem`).
+ *
+ * This is the format `openssl ca` itself writes and reads; every mutating
+ * method here (`nextSerial`, `nextCrlNumber`, `appendIssued`, `markRevoked`,
+ * `storeCertificate`) exists so a native (non-openssl) signing backend can
+ * write the exact same on-disk format `openssl ca` does, so an install can
+ * move between backends and external `openssl` tooling keeps working on the
+ * same directory. Callers are responsible for serializing access — every
+ * mutating call must happen under the owning CA's directory lock
+ * (`CertificateAuthority._withCaDirectoryLock`), the same guarantee
+ * `OpenSslCaBackend` gets from the lock around each `openssl ca` /
+ * `openssl x509 -CAserial` invocation.
+ */
+declare class CaDatabase {
+    #private;
+    constructor(rootDir: string);
+    /** Path to the OpenSSL certificate database file (`index.txt`). */
+    get indexFile(): string;
+    /**
+     * Parse the OpenSSL `index.txt` certificate database.
+     *
+     * Each line has tab-separated fields:
+     * ```
+     * status  expiry  [revocationDate]  serial  unknown  subject
+     * ```
+     *
+     * - status: `V` (valid), `R` (revoked), `E` (expired)
+     * - expiry: `YYMMDDHHmmssZ`
+     * - revocationDate: present only for revoked certs
+     * - serial: hex string
+     * - unknown: always `"unknown"`
+     * - subject: X.500 slash-delimited string
+     */
+    readIndex(): IssuedCertificateRecord[];
+    /** Look up one record by serial number (case-insensitive). */
+    findBySerial(serial: string): IssuedCertificateRecord | undefined;
+    /**
+     * Read a specific issued certificate by serial number.
+     *
+     * OpenSSL stores signed certificates in the `certs/` directory using
+     * the naming convention `<SERIAL>.pem`.
+     *
+     * @param serial - hex-encoded serial number (e.g. `"1000"`)
+     * @returns the DER buffer, or `undefined` if not found
+     */
+    getCertificateBySerial(serial: string): Buffer | undefined;
+    /** Hand out the next certificate serial number, bumping the `serial` file. */
+    nextSerial(): string;
+    /** Hand out the next CRL number, bumping the `crlnumber` file. */
+    nextCrlNumber(): string;
+    /** Append a newly-issued certificate's `V` (valid) row to `index.txt`. */
+    appendIssued(record: {
+        serial: string;
+        expiryDate: Date;
+        subject: string;
+    }): void;
+    /**
+     * Rewrite a certificate's `index.txt` row from `V` to `R` (revoked).
+     * Throws if the serial is not found, or is already revoked — the same
+     * "already revoked" case `openssl ca -revoke` itself rejects.
+     */
+    markRevoked(serial: string, revocationDate: Date, reason: string): void;
+    /** Store a signed certificate's PEM under `certs/<SERIAL>.pem`, as `openssl ca` does. */
+    storeCertificate(serial: string, pem: string): void;
+}
+
+/** Default X.500 subject used when no custom subject is provided. */
+declare const defaultSubject = "/C=FR/ST=IDF/L=Paris/O=Local NODE-OPCUA Certificate Authority/CN=NodeOPCUA-CA";
+declare const configurationFileTemplate: string;
+/**
+ * Escape a value for use inside a double-quoted openssl config value.
+ *
+ * openssl's config parser (crypto/conf/conf_def.c) treats an unquoted value
+ * specially: `$var` / `${var}` / `$(var)` are expanded, and `'`, `"` and the
+ * backtick are all quote characters (a backtick pair is silently removed).
+ * Inside a double-quoted value none of that applies: characters are copied
+ * verbatim except a backslash, which escapes the next character. So a path
+ * containing `$`, backticks, `#` or spaces is safe once double-quoted with
+ * `\` and `"` escaped.
+ */
+declare function escapeOpensslConfDoubleQuoted(value: string): string;
+/**
+ * Render the CA openssl configuration for `caRootDir`. The root folder is
+ * emitted forward-slashed (openssl accepts that on every platform) and
+ * double-quoted, so a CA `location` containing characters that openssl's
+ * config syntax would otherwise interpret (`$`, backticks, `#`, quotes) is
+ * taken literally.
+ */
+declare function renderCaConfig(caRootDir: string): string;
+/**
+ * Result of {@link CertificateAuthority.initializeCSR}.
+ *
+ * - `"ready"` — the CA certificate already exists and is valid.
+ * - `"pending"` — key + CSR exist but no cert; waiting for external signing.
+ * - `"created"` — a fresh key + CSR were just generated.
+ * - `"expired"` — the CA certificate has expired (or will expire within
+ *   the configured threshold). A new CSR has been generated for renewal
+ *   while preserving the existing private key.
+ */
+type InitializeCSRResult = {
+    status: "ready";
+} | {
+    status: "pending";
+    csrPath: string;
+} | {
+    status: "created";
+    csrPath: string;
+} | {
+    status: "expired";
+    csrPath: string;
+    expiryDate: Date;
+};
+/**
+ * Result of {@link CertificateAuthority.installCACertificate}.
+ *
+ * - `"success"` — the certificate was installed and CRL generated.
+ * - `"error"` — the certificate was rejected (see `reason`).
+ */
+type InstallCACertificateResult = {
+    status: "success";
+} | {
+    status: "error";
+    reason: string;
+    message: string;
+};
+/**
+ * Options for creating a {@link CertificateAuthority}.
+ */
+interface CertificateAuthorityCoreOptions {
+    /** RSA key size for the CA private key. */
+    keySize: KeySize;
+    /** Filesystem path where the CA directory structure is stored. */
+    location: string;
+    /**
+     * X.500 subject for the CA certificate.
+     * Accepts a slash-delimited string (e.g. `"/CN=My CA/O=Acme"`) or
+     * a structured {@link SubjectOptions} object.
+     *
+     * @defaultValue {@link defaultSubject}
+     */
+    subject?: string | SubjectOptions;
+    /**
+     * Parent CA that will sign this CA's certificate.
+     * If omitted, the CA is self-signed (root CA).
+     * The parent CA must be initialized before this CA.
+     */
+    issuerCA?: CertificateAuthorityCore;
+    /**
+     * Public URL (http/https) where the CRL produced by this CA is
+     * reachable. When set, every issued certificate carries an
+     * X.509v3 `crlDistributionPoints` extension pointing at this URL.
+     *
+     * Leave undefined to omit the extension entirely (opt-in — see
+     * US-202).  Validated synchronously at construction / setter call.
+     */
+    crlDistributionUrl?: string;
+    /**
+     * Public URL of the OCSP responder. When set, every issued cert
+     * carries an `authorityInfoAccess` extension with an `OCSP` leg
+     * pointing at this URL. Leave undefined to omit (US-202).
+     */
+    ocspResponderUrl?: string;
+    /**
+     * Public URL where the issuer's certificate can be fetched.
+     * When set, the `authorityInfoAccess` extension on every issued
+     * cert carries a `caIssuers` leg pointing at this URL (chain
+     * repair). Leave undefined to omit (US-202).
+     */
+    caIssuersUrl?: string;
+    /**
+     * Encrypt the CA private key (`private/cakey.pem`) at rest with this
+     * passphrase (opt-in, default off). When set:
+     * - a freshly generated CA key is written as encrypted PKCS#8;
+     * - an existing *plaintext* CA key is encrypted in place by
+     *   {@link CertificateAuthority.initialize} / `initializeCSR()`;
+     * - every `openssl` invocation that loads the CA key (CSR, self-sign,
+     *   sign, revoke, CRL generation) receives it via `-passin env:`, never
+     *   in argv; a missing or wrong passphrase fails `initialize()` closed.
+     *
+     * A function is called at most once per instance; the resolved
+     * passphrase is kept in memory for the instance's lifetime because the
+     * CA hands it to each openssl child. Never logged.
+     *
+     * A subordinate CA (`issuerCA` set) uses the *issuer's* passphrase for
+     * the issuer's key: construct the parent with its own option.
+     */
+    privateKeyPassphrase?: PrivateKeyPassphrase;
+    /**
+     * Who actually signs, and writes the certificate database. Supplying it
+     * is the whole point of this class: nothing here names a concrete
+     * backend, so a program that only ever uses the native one never
+     * references - and never has to ship - the openssl one.
+     *
+     * {@link CertificateAuthority} is the batteries-included subclass that
+     * picks a backend for you from a `"openssl" | "native"` option.
+     */
+    backend: CaBackend;
+    /**
+     * Sign with an external key that never leaves its holder - an HSM or a
+     * cloud KMS - instead of `private/cakey.pem`. The signer exposes only
+     * `getPublicKey()` and `sign(tbs)`; this class builds the to-be-signed
+     * bytes locally and asks the signer for the signature.
+     *
+     * Setting this implies `backend: "native"` (the openssl CLI can only
+     * load a key from a file, so it cannot honour a signer); combining it
+     * with an explicit `backend: "openssl"` is a constructor error. No
+     * `private/cakey.pem` is generated, and the key-file operations that
+     * cannot apply - {@link CertificateAuthority.getPrivateKey} and
+     * {@link CertificateAuthority.reencryptPrivateKey} - throw.
+     */
+    signer?: CaSigner;
+}
+
+/**
+ * Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
+ *
+ * All fields are optional. When provided, they override the
+ * corresponding values from the CSR.
+ */
+interface SignCertificateOptions {
+    /** Certificate validity in days (default: 365). */
+    validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
+    /** Override the certificate start date. */
+    startDate?: Date;
+    /** Override DNS SANs. */
+    dns?: string[];
+    /** Override IP SANs. */
+    ip?: string[];
+    /** Override the application URI SAN. */
+    applicationUri?: string;
+    /** Override the X.500 subject. */
+    subject?: SubjectOptions | string;
+}
+/**
+ * Capabilities advertised by a PKI backend (or by this
+ * {@link CertificateAuthority}) so consumers can clamp requested
+ * validity to the limits the backend can actually honor.
+ *
+ * Useful for the GDS Pull / Push management flows, where the CA may
+ * be supplied by an external service (step-ca, EJBCA, …) with its
+ * own minimum / maximum / granularity constraints.
+ *
+ * @see CertificateAuthority.getCapabilities
+ */
+interface PkiBackendCapabilities {
+    /** Smallest validity this backend can issue, in milliseconds. */
+    minValidityMs: number;
+    /** Largest validity this backend will issue, in milliseconds. */
+    maxValidityMs: number;
+    /**
+     * Validity is rounded up to the nearest multiple of this many
+     * milliseconds. For `node-opcua-pki`'s OpenSSL-based CA this is
+     * 1 000 ms (one second — the X.509 floor per RFC 5280 §4.1.2.5).
+     */
+    validityGranularityMs: number;
+    /**
+     * Native unit the backend works in. Diagnostic only — callers
+     * always pass `validityMs` (US-208 / US-210).
+     */
+    nativeUnit: "second" | "minute" | "hour" | "day";
+}
+/**
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
+ */
+interface GenerateKeyPairAndSignOptions {
+    /** OPC UA application URI (required). */
+    applicationUri: string;
+    /** X.500 subject for the certificate (e.g. "CN=MyApp"). */
+    subject?: SubjectOptions | string;
+    /** DNS host names for the SAN extension. */
+    dns?: string[];
+    /** IP addresses for the SAN extension. */
+    ip?: string[];
+    /** Certificate validity in days (default: 365). */
+    validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
+    /** Certificate start date (default: now). */
+    startDate?: Date;
+    /** RSA key size in bits (default: 2048). */
+    keySize?: KeySize;
+}
+/**
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
+ *
+ * Extends the DER options with an optional `passphrase` to protect
+ * the PFX bundle.
+ */
+interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
+    /**
+     * Passphrase to protect the PFX file.
+     * If omitted, the PFX is created without a password.
+     */
+    passphrase?: string;
+}
+declare class CertificateAuthorityCore {
+    #private;
+    /** RSA key size used when generating the CA private key. */
+    readonly keySize: KeySize;
+    /** Root filesystem path of the CA directory structure. */
+    readonly location: string;
+    /** X.500 subject of the CA certificate. */
+    readonly subject: Subject;
+    /** @internal Parent CA (undefined for root CAs). */
+    readonly _issuerCA?: CertificateAuthorityCore;
+    /** @internal Configured CDP / AIA URLs (US-202). */
+    private _crlDistributionUrl?;
+    private _ocspResponderUrl?;
+    private _caIssuersUrl?;
+    constructor(options: CertificateAuthorityCoreOptions);
+    /**
+     * Public URL where the CRL produced by this CA is reachable, or
+     * `undefined` if no CDP extension should be emitted on issued certs.
+     */
+    get crlDistributionUrl(): string | undefined;
+    /**
+     * Public URL of the OCSP responder, or `undefined` if no AIA OCSP
+     * leg should be emitted on issued certs.
+     */
+    get ocspResponderUrl(): string | undefined;
+    /**
+     * Public URL where the issuer's certificate can be fetched, or
+     * `undefined` if no AIA caIssuers leg should be emitted.
+     */
+    get caIssuersUrl(): string | undefined;
+    /**
+     * Configure the URL embedded as `crlDistributionPoints` in every
+     * subsequently-issued certificate. Pass `undefined` to disable
+     * the extension entirely. Validated synchronously — throws on
+     * empty string, non-http(s) protocol, missing path. Warns (does
+     * not throw) when the URL points at loopback.
+     *
+     * @see US-202
+     */
+    setCrlDistributionUrl(url: string | undefined): void;
+    /**
+     * Configure the OCSP responder URL embedded as the `OCSP` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setOcspResponderUrl(url: string | undefined): void;
+    /**
+     * Configure the caIssuers URL embedded as the `caIssuers` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setCaIssuersUrl(url: string | undefined): void;
+    /** Absolute path to the CA root directory (alias for {@link location}). */
+    get rootDir(): string;
+    /** Path to the OpenSSL configuration file (`conf/caconfig.cnf`). */
+    get configFile(): string;
+    /** Path to the CA private key (`private/cakey.pem`); may be passphrase-encrypted, see {@link getPrivateKey}. */
+    get privateKey(): string;
+    /**
+     * The CA private key, decrypted with the configured `privateKeyPassphrase`
+     * if it is encrypted. Fails closed (`PrivateKeyPassphraseRequiredError`)
+     * on an encrypted key with no or the wrong passphrase.
+     */
+    getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * True when this CA signs with an external {@link CaSigner} (HSM/KMS)
+     * rather than with `private/cakey.pem`. There is then no private key
+     * file on disk, and never was one.
+     */
+    get hasExternalSigner(): boolean;
+    /**
+     * @internal The key every signing operation goes through. An injected
+     * {@link CaSigner} is returned as-is; otherwise the on-disk key is read
+     * (and decrypted) and handed over as a plain `CryptoKey`. Both are
+     * accepted by the `node-opcua-crypto` signing primitives, so callers
+     * never branch on which one they got.
+     */
+    _getSigningKey(): Promise<CryptoKey | CaSigner>;
+    /**
+     * Enable, disable, or rotate the passphrase protecting `private/cakey.pem`
+     * (temp file + atomic rename, temp file removed on failure). Only
+     * rewrites the file: construct a new `CertificateAuthority` with the new
+     * passphrase to continue using it.
+     */
+    reencryptPrivateKey(oldPassphrase?: PrivateKeyPassphrase, newPassphrase?: PrivateKeyPassphrase): Promise<void>;
+    /** @internal resolve the configured passphrase, at most once per instance */
+    _privateKeyPassphrase(): Promise<string | undefined>;
+    /**
+     * @internal On an existing key: encrypt it in place if a passphrase is
+     * configured and it is still plaintext (secure by default: the option
+     * means "protect this key", not "ignore me"), then read it back so a
+     * wrong or missing passphrase fails initialize() closed rather than the
+     * first signing operation.
+     */
+    _ensurePrivateKeyProtection(): Promise<void>;
+    /**
+     * @internal Run `action` under this CA's directory lock. For the one
+     * legitimate cross-instance use: a subordinate CA's bootstrap signs its
+     * certificate with `openssl x509 -CAserial`, which read-increment-writes
+     * THIS issuer's `serial` file, and must therefore hold this issuer's
+     * lock (ordering is always subordinate -> issuer, so no cycle).
+     */
+    _withCaDirectoryLock<T>(action: () => Promise<T>): Promise<T>;
+    /** Path to the CA certificate in PEM format (`public/cacert.pem`). */
+    get caCertificate(): string;
+    /**
+     * Path to the issuer certificate chain (`public/issuer_chain.pem`).
+     *
+     * This file is created by {@link installCACertificate} when the
+     * provided cert file contains additional issuer certificates
+     * (e.g. intermediate + root). It is appended to signed certs
+     * by {@link constructCertificateChain} to produce a full chain
+     * per OPC UA Part 6 §6.2.6.
+     */
+    get issuerCertificateChain(): string;
+    /**
+     * Path to the current Certificate Revocation List in DER format.
+     * (`crl/revocation_list.der`)
+     */
+    get revocationListDER(): string;
+    /**
+     * Path to the current Certificate Revocation List in PEM format.
+     * (`crl/revocation_list.crl`)
+     */
+    get revocationList(): string;
+    /**
+     * Path to the concatenated CA certificate + CRL file.
+     * Used by OpenSSL for CRL-based verification.
+     */
+    get caCertificateWithCrl(): string;
+    /**
+     * Return the CA certificate as a DER-encoded buffer.
+     *
+     * @throws if the CA certificate file does not exist
+     *   (call {@link initialize} first).
+     */
+    getCACertificateDER(): Buffer;
+    /**
+     * Return the CA certificate as a PEM-encoded string.
+     *
+     * @throws if the CA certificate file does not exist
+     *   (call {@link initialize} first).
+     */
+    getCACertificatePEM(): string;
+    /**
+     * Return the current Certificate Revocation List as a
+     * DER-encoded buffer.
+     *
+     * Returns an empty buffer if no CRL has been generated yet.
+     */
+    getCRLDER(): Buffer;
+    /**
+     * Return the current Certificate Revocation List as a
+     * PEM-encoded string.
+     *
+     * Returns an empty string if no CRL has been generated yet.
+     */
+    getCRLPEM(): string;
+    /**
+     * Return a list of all issued certificates recorded in the
+     * OpenSSL `index.txt` database.
+     *
+     * Each entry includes the serial number, subject, status,
+     * expiry date, and (for revoked certs) the revocation date.
+     */
+    getIssuedCertificates(): IssuedCertificateRecord[];
+    /**
+     * Return the total number of certificates recorded in
+     * `index.txt`.
+     */
+    getIssuedCertificateCount(): number;
+    /**
+     * Return the status of a certificate by its serial number.
+     *
+     * @param serial - hex-encoded serial number (e.g. `"1000"`)
+     * @returns `"valid"`, `"revoked"`, `"expired"`, or
+     *   `undefined` if not found
+     */
+    getCertificateStatus(serial: string): "valid" | "revoked" | "expired" | undefined;
+    /**
+     * Read a specific issued certificate by serial number and
+     * return its content as a DER-encoded buffer.
+     *
+     * OpenSSL stores signed certificates in the `certs/`
+     * directory using the naming convention `<SERIAL>.pem`.
+     *
+     * @param serial - hex-encoded serial number (e.g. `"1000"`)
+     * @returns the DER buffer, or `undefined` if not found
+     */
+    getCertificateBySerial(serial: string): Buffer | undefined;
+    /**
+     * Path to the OpenSSL certificate database file.
+     */
+    get indexFile(): string;
+    /**
+     * Sign a DER-encoded Certificate Signing Request and return
+     * the signed certificate as a DER buffer.
+     *
+     * This method handles temp-file creation and cleanup
+     * internally so that callers can work with in-memory
+     * buffers only.
+     *
+     * The CA can override fields from the CSR by passing
+     * `options.dns`, `options.ip`, `options.applicationUri`,
+     * `options.startDate`, or `options.subject`.
+     *
+     * @param csrDer - the CSR as a DER-encoded buffer
+     * @param options - signing options and CA overrides
+     * @returns the signed certificate as a DER-encoded buffer
+     */
+    signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
+    /**
+     * Advertise the validity limits this CA can honor.
+     *
+     * Consumers (notably the GDS server in [`cert_auth.ts`](https://github.com/sterfive/node-opcua-gds))
+     * clamp a requested validity against these bounds before calling
+     * {@link signCertificateRequestFromDER}, so a misconfigured
+     * `defaultCertValidity` cannot ask the CA for something it cannot
+     * produce.
+     *
+     * Defaults match the OpenSSL-backed implementation:
+     * - `minValidityMs = 60_000` (1 minute) — practical floor; the
+     *   X.509 spec floor is 1 second but very short certs are rarely
+     *   useful and pathological for any real deployment.
+     * - `maxValidityMs = 10 * 365 * 86_400_000` (≈ 10 years) — long
+     *   enough for root CAs.
+     * - `validityGranularityMs = 1_000` (1 second) — RFC 5280 §4.1.2.5
+     *   floor on `notBefore` / `notAfter`.
+     * - `nativeUnit = "second"` — what `x509Date()` actually encodes.
+     *
+     * @see US-208 — the consumer-side capability story.
+     */
+    getCapabilities(): PkiBackendCapabilities;
+    generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
+        certificateDer: Buffer;
+        privateKey: PrivateKey;
+    }>;
+    /**
+     * Generate a new RSA key pair, create an internal CSR, sign it
+     * with this CA, and return the result as a PKCS#12 (PFX)
+     * buffer bundling the certificate, private key, and CA chain.
+     *
+     * The private key is **never stored** by the CA — it exists only
+     * in a temporary directory that is cleaned up after the operation.
+     *
+     * @param options - key generation, certificate, and PFX options
+     * @returns the PFX as a `Buffer`
+     */
+    generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
+    /**
+     * Revoke a DER-encoded certificate and regenerate the CRL.
+     *
+     * Extracts the serial number from the certificate, then
+     * uses the stored cert file at `certs/<serial>.pem` for
+     * revocation — avoiding temp-file PEM format mismatches.
+     *
+     * @param certDer - the certificate as a DER-encoded buffer
+     * @param reason - CRL reason code
+     *   (default: `"keyCompromise"`)
+     * @throws if the certificate's serial is not found in the CA
+     */
+    revokeCertificateDER(certDer: Buffer, reason?: string): Promise<void>;
+    /**
+     * Initialize the CA directory structure, generate the CA
+     * private key and self-signed certificate if they do not
+     * already exist.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize the CA directory structure and generate the
+     * private key + CSR **without signing**.
+     *
+     * Use this when the CA certificate will be signed by an
+     * external (third-party) root CA.  After receiving the signed
+     * certificate, call {@link installCACertificate} to complete
+     * the setup.
+     *
+     * **Idempotent / restart-safe:**
+     * - If the CA certificate exists and is valid → `{ status: "ready" }`
+     * - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
+     *   (a new CSR is generated, preserving the existing private key)
+     * - If key + CSR exist but no cert (restart before install) →
+     *   `{ status: "pending", csrPath }` without regenerating
+     * - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
+     *
+     * @returns an {@link InitializeCSRResult} describing the CA state
+     */
+    initializeCSR(): Promise<InitializeCSRResult>;
+    /**
+     * Check whether the CA certificate needs renewal and, if so,
+     * generate a new CSR for re-signing by the external root CA.
+     *
+     * Use this while the CA is running to detect upcoming expiry
+     * **before** it actually expires. The existing private key is
+     * preserved so previously issued certs remain valid.
+     *
+     * @param thresholdDays - number of days before expiry at which
+     *   to trigger renewal (default: 30)
+     * @returns an {@link InitializeCSRResult} — `"expired"` if
+     *   renewal is needed, `"ready"` if the cert is still valid
+     */
+    renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
+    /**
+     * Generate a CSR using the existing private key.
+     * Must be called under {@link #withCaLock} — the lock is taken by the
+     * public callers (`initializeCSR`, `renewCSR`), not here, so that
+     * `initializeCSR` can hold one lock across key generation AND CSR
+     * generation without the non-reentrant file lock deadlocking.
+     * @internal
+     */
+    private _generateCSR;
+    /**
+     * Install an externally-signed CA certificate and generate
+     * the initial CRL.
+     *
+     * Call this after {@link initializeCSR} once the external
+     * root CA has signed the CSR.
+     *
+     * **Safety checks:**
+     * - Verifies that the certificate's public key matches the
+     *   CA private key before installing.
+     *
+     * @param signedCertFile - path to the PEM-encoded signed
+     *   CA certificate (issued by the external root CA)
+     * @returns an {@link InstallCACertificateResult} with
+     *   `status: "success"` or `status: "error"` and a `reason`
+     */
+    installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
+    /**
+     * Sign a CSR with CA extensions (`v3_ca`), producing a
+     * subordinate CA certificate.
+     *
+     * Unlike {@link signCertificateRequest} which signs with
+     * end-entity extensions (SANs, etc.), this method signs
+     * with `basicConstraints = CA:TRUE` and `keyUsage =
+     * keyCertSign, cRLSign`.
+     *
+     * @param certFile - output path for the signed CA cert (PEM)
+     * @param csrFile - path to the subordinate CA's CSR
+     * @param params - signing parameters
+     */
+    signCACertificateRequest(certFile: string, csrFile: string, params: {
+        validity?: number;
+    }): Promise<void>;
+    /**
+     * Rebuild the combined CA certificate + CRL file.
+     *
+     * This concatenates the CA certificate with the current
+     * revocation list so that OpenSSL can verify certificates
+     * with CRL checking enabled.
+     */
+    constructCACertificateWithCRL(): Promise<void>;
+    /**
+     * Append the CA certificate to a signed certificate file,
+     * creating a PEM certificate chain.
+     *
+     * @param certificate - path to the certificate file to extend
+     */
+    constructCertificateChain(certificate: Filename): Promise<void>;
+    /**
+     * Create a self-signed certificate using OpenSSL.
+     *
+     * @param certificateFile - output path for the signed certificate
+     * @param privateKey - path to the private key file
+     * @param params - certificate parameters (subject, validity, SANs)
+     */
+    createSelfSignedCertificate(certificateFile: Filename, privateKey: Filename, params: Params): Promise<void>;
+    /**
+     * Regenerate `crl/revocation_list.{crl,der}` from the current database
+     * state, without changing any certificate's status. Normally
+     * unnecessary — `revokeCertificate` already regenerates the CRL as
+     * part of revoking — but useful to force a refresh (e.g. after
+     * switching a CA's `backend` between `"openssl"` and `"native"`).
+     */
+    regenerateCrl(): Promise<void>;
+    /**
+     * Revoke a certificate and regenerate the CRL.
+     *
+     * @param certificate - path to the certificate file to revoke
+     * @param params - revocation parameters
+     * @param params.reason - CRL reason code
+     *   (default `"keyCompromise"`)
+     */
+    revokeCertificate(certificate: Filename, params: Params): Promise<void>;
+    /**
+     * Sign a Certificate Signing Request (CSR) with this CA.
+     *
+     * The signed certificate is written to `certificate`, and the
+     * CA certificate chain plus CRL are appended to form a
+     * complete certificate chain.
+     *
+     * @param certificate - output path for the signed certificate
+     * @param certificateSigningRequestFilename - path to the CSR
+     * @param params1 - signing parameters (validity, dates, SANs)
+     * @returns the path to the signed certificate
+     */
+    signCertificateRequest(certificate: Filename, certificateSigningRequestFilename: Filename, params1: Params): Promise<Filename>;
+    /**
+     * Check that `certificate` really was signed by this CA, and throw if it
+     * was not.
+     *
+     * This used to do nothing: `openssl verify` crashes on Windows, so the
+     * check was left as a placeholder. It no longer needs a subprocess -
+     * `verifyCertificateSignature` does it in pure JS, the same way
+     * {@link CertificateManager} already validates a chain - so the check
+     * that `signCertificateRequest` always claimed to perform now actually
+     * happens on every issuance, whichever backend did the signing.
+     *
+     * Only the leading certificate is examined: the file may be a chain,
+     * and the rest of it is this CA's own certificate and its issuers.
+     *
+     * @param certificate - path to the certificate (or chain) to verify
+     */
+    verifyCertificate(certificate: Filename): Promise<void>;
+}
+
+/**
+ * Everything a {@link CertificateAuthorityCore} delegates to a signing backend:
+ * the operations that need the CA's private key, or that mutate the CA's
+ * certificate database (`index.txt`, `serial`, `crlnumber`,
+ * `certs/<SERIAL>.pem`, `crl/revocation_list.*`). Everything else — directory
+ * layout, PEM/DER file concatenation, `index.txt` *reading*, URL validation,
+ * passphrase handling, `initializeCSR`'s state machine — stays in
+ * {@link CertificateAuthorityCore} and is shared by every backend.
+ *
+ * Two implementations exist. `OpenSslCaBackend` shells out to the `openssl`
+ * CLI exactly as `CertificateAuthority` always has, and remains the default.
+ * `NativeCaBackend` does the same work in pure JS, which is what allows a
+ * CA key held by an HSM or KMS - one that only signs and never exposes key
+ * material - to be used at all: the openssl CLI can only load a key from a
+ * file. Both write the same on-disk database format, so an install can move
+ * between them and external `openssl` tooling keeps working either way.
+ */
+interface CaBackend {
+    /**
+     * Whether this backend can sign with an external {@link CaSigner} - an
+     * HSM or KMS key that only signs and never exposes key material.
+     * `false` for a backend that can only load a key from a file, so the
+     * CA can refuse the combination up front instead of failing later.
+     */
+    readonly supportsExternalSigner: boolean;
+    /**
+     * Check whatever this backend needs before it can do any work, and
+     * throw if it is missing. `CertificateAuthority` calls it before
+     * delegating, so a missing prerequisite is reported once, up front,
+     * rather than as a failure part-way through an operation.
+     *
+     * This exists because the requirement is the backend's, not the CA's:
+     * the openssl backend needs the `openssl` executable on PATH, and the
+     * native one needs nothing at all. Asking the CA to know that is what
+     * made a `backend: "native"` CA refuse to issue a certificate on a
+     * machine without openssl installed.
+     */
+    preflight(): Promise<void>;
+    /**
+     * Generate the CA's private key (if missing) and its certificate:
+     * self-signed for a root CA, signed by `ca._issuerCA` for a subordinate.
+     * Also produces the initial CRL. Called once, from
+     * {@link CertificateAuthority.initialize}.
+     */
+    bootstrap(ca: CertificateAuthorityCore): Promise<void>;
+    /**
+     * Generate a CSR for the CA's own key (`[v3_ca_req]` profile) — used by
+     * `initializeCSR`/`renewCSR` when the CA certificate is signed
+     * externally.
+     */
+    generateCaCsr(ca: CertificateAuthorityCore, caRootDir: string, privateKeyFile: string, csrFile: string): Promise<void>;
+    /**
+     * Sign a subordinate CA's CSR with this CA's key (`[v3_ca]` profile).
+     * Used by {@link CertificateAuthority.signCACertificateRequest}.
+     */
+    signSubordinateCsr(ca: CertificateAuthorityCore, csrFile: string, certFile: string, validityDays: number): Promise<void>;
+    /**
+     * Sign an end-entity CSR with this CA's key (`[usr_cert]` profile via
+     * `openssl ca`) — the certificate database (`index.txt`, `serial`,
+     * `certs/<SERIAL>.pem`) is updated as a side effect. Used by
+     * {@link CertificateAuthority.signCertificateRequest}.
+     *
+     * `sanOverride` is the applicationUri/dns/ip the caller already
+     * re-derived from the CSR itself (SANs are not copied by `openssl ca`
+     * — see the comment at the call site), so the backend can render the
+     * `subjectAltName` extension without re-parsing the CSR.
+     */
+    signEndEntityCsr(ca: CertificateAuthorityCore, certificate: string, csr: string, params: Params, sanOverride: Required<ProcessAltNamesParam>): Promise<void>;
+    /**
+     * Mark a certificate revoked in the database and regenerate the CRL.
+     * Used by {@link CertificateAuthority.revokeCertificate}.
+     */
+    revoke(ca: CertificateAuthorityCore, certificate: string, reason: string): Promise<void>;
+    /**
+     * Regenerate `crl/revocation_list.{crl,der}` from the current database
+     * state, without changing any certificate's status. Used after
+     * {@link CertificateAuthority.installCACertificate} installs an
+     * externally-signed CA certificate.
+     */
+    regenerateCrl(ca: CertificateAuthorityCore): Promise<void>;
+    /**
+     * Legacy CLI self-signed certificate creation (`openssl req` +
+     * `openssl ca -selfsign`). Used by
+     * {@link CertificateAuthority.createSelfSignedCertificate}.
+     */
+    createSelfSignedCertificate(ca: CertificateAuthorityCore, certificateFile: string, privateKeyFile: string, params: Params): Promise<void>;
+}
+
+/**
+ * A native (pure-JS, no `openssl` child process) {@link CaBackend}: it
+ * bootstraps a CA, signs end-entity and subordinate-CA requests, revokes,
+ * and builds CRLs entirely through `node-opcua-crypto`'s signing
+ * primitives and {@link CaDatabase}'s write path, so the resulting
+ * `index.txt`/`serial`/`crlnumber`/`certs/` are the same on-disk format
+ * `openssl ca` produces and an install can move between backends.
+ *
+ * The signing key reaches every operation through
+ * `CertificateAuthority._getSigningKey()`, which yields either the on-disk
+ * key or an external `CaSigner`. Nothing below can tell the difference,
+ * which is the point: a CA whose key lives in an HSM never has a
+ * `private/cakey.pem` and never needs one.
+ *
+ * Two deliberate differences from the openssl backend, both improvements:
+ * a subordinate CA's certificate is recorded in the issuer's `index.txt`
+ * (`openssl x509 -CAserial` bumps the serial file but records nothing),
+ * and a subordinate's SAN is taken from its own CSR rather than being
+ * stamped with the issuer's.
+ */
+declare class NativeCaBackend implements CaBackend {
+    #private;
+    /** Nothing to check: this backend spawns no process and needs no tool on PATH. */
+    /** Signing goes through `ca._getSigningKey()`, which may be an external signer. */
+    readonly supportsExternalSigner = true;
+    preflight(): Promise<void>;
+    /**
+     * Write a CSR for the CA's own key, the `[v3_ca_req]` equivalent. The
+     * key comes from the CA rather than from `privateKeyFile`: on a
+     * signer-backed CA that file does not exist.
+     */
+    generateCaCsr(ca: CertificateAuthorityCore, _caRootDir: string, _privateKeyFile: string, csrFile: string): Promise<void>;
+    bootstrap(ca: CertificateAuthorityCore): Promise<void>;
+    /** Sign a subordinate CA's request with this CA's key, the `[v3_ca]` equivalent. */
+    signSubordinateCsr(ca: CertificateAuthorityCore, csrFile: string, certFile: string, validityDays: number): Promise<void>;
+    /**
+     * Self-sign a certificate with a caller-supplied key file and record it
+     * in this CA's database: the native equivalent of `openssl req -new`
+     * followed by `openssl ca -selfsign`, which likewise applies the
+     * end-entity profile and updates `index.txt`.
+     */
+    createSelfSignedCertificate(ca: CertificateAuthorityCore, certificateFile: string, privateKeyFile: string, params: Params): Promise<void>;
+    signEndEntityCsr(ca: CertificateAuthorityCore, certificate: string, csr: string, params: Params, sanOverride: Required<ProcessAltNamesParam>): Promise<void>;
+    regenerateCrl(ca: CertificateAuthorityCore): Promise<void>;
+    revoke(ca: CertificateAuthorityCore, certificate: string, reason: string): Promise<void>;
+}
+
+export { type CaBackend as C, type Filename as F, type GenerateKeyPairAndSignOptions as G, type InitializeCSRResult as I, type KeySize as K, NativeCaBackend as N, type Params as P, type SignCertificateOptions as S, type Thumbprint as T, CertificateAuthorityCore as a, type ProcessAltNamesParam as b, type CertificateAuthorityCoreOptions as c, type PrivateKeyPassphrase as d, type PrivateKeyProvider as e, type CreateSelfSignCertificateParam as f, type CertificateStatus as g, type CreateCertificateSigningRequestOptions as h, type CreateCertificateSigningRequestWithConfigOptions as i, type CreateSelfSignCertificateWithConfigParam as j, type GenerateKeyPairAndSignPFXOptions as k, type InstallCACertificateResult as l, type KeyLength as m, type PkiBackendCapabilities as n, type StartDateEndDateParam as o, adjustApplicationUri as p, adjustDate as q, quote as r, resolvePrivateKeyPassphrase as s, CaDatabase as t, type IssuedCertificateRecord as u, configurationFileTemplate as v, defaultSubject as w, escapeOpensslConfDoubleQuoted as x, renderCaConfig as y };