node-opcua-pki 6.22.1 → 7.0.0

package/dist/{core-BwqSJPHc.d.mts → lib/ca/core/certificate_authority_core.d.ts}

@@ -1,250 +1,10 @@
-import { SubjectOptions, PrivateKey, CaSigner, CertificatePurpose, Subject } 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: a filesystem path to a PEM file (unencrypted;
-     * the historical behavior), an already-resolved in-memory
-     * {@link PrivateKey}, or an opaque {@link CaSigner} (HSM/KMS-held key;
-     * only the openssl-free toolbox supports it — openssl needs a key file)
-     * — see {@link CreateSelfSignCertificateWithConfigParam.privateKey}.
-     */
-    privateKey: Filename | PrivateKey | CaSigner;
-    /** Intended purpose of the certificate. */
-    purpose: CertificatePurpose;
-}
-/**
- * Narrows the `privateKey` union of the toolbox options: a {@link CaSigner}
- * is the only member that carries a `sign` method — a path is a string and
- * a {@link PrivateKey} envelope has only `hidden`.
- */
-declare function isOpaqueSigner(privateKey: Filename | PrivateKey | CaSigner): privateKey is CaSigner;
-/**
- * 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: a filesystem path to a PEM file (unencrypted;
-     * the historical behavior), 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 — or an opaque {@link CaSigner} (HSM/KMS-held key; only
-     * the openssl-free toolbox supports it — openssl needs a key file).
-     */
-    privateKey: Filename | PrivateKey | CaSigner;
-    /** 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;
-}
-
+import { type CaSigner, type PrivateKey, Subject, type SubjectOptions } from "node-opcua-crypto";
+import { type Filename, type KeySize, type Params, type PrivateKeyPassphrase } from "../../toolbox/index.js";
+import type { CaBackend } from "./ca_backend.js";
+import { type IssuedCertificateRecord } from "./ca_database.js";
 /** 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;
+export declare const defaultSubject = "/C=FR/ST=IDF/L=Paris/O=Local NODE-OPCUA Certificate Authority/CN=NodeOPCUA-CA";
+export declare const configurationFileTemplate: string;
 /**
  * Escape a value for use inside a double-quoted openssl config value.
  *
@@ -256,7 +16,7 @@ declare const configurationFileTemplate: string;
  * containing `$`, backticks, `#` or spaces is safe once double-quoted with
  * `\` and `"` escaped.
  */
-declare function escapeOpensslConfDoubleQuoted(value: string): string;
+export 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
@@ -264,7 +24,7 @@ declare function escapeOpensslConfDoubleQuoted(value: string): string;
  * config syntax would otherwise interpret (`$`, backticks, `#`, quotes) is
  * taken literally.
  */
-declare function renderCaConfig(caRootDir: string): string;
+export declare function renderCaConfig(caRootDir: string): string;
 /**
  * Result of {@link CertificateAuthority.initializeCSR}.
  *
@@ -275,7 +35,7 @@ declare function renderCaConfig(caRootDir: string): string;
  *   the configured threshold). A new CSR has been generated for renewal
  *   while preserving the existing private key.
  */
-type InitializeCSRResult = {
+export type InitializeCSRResult = {
     status: "ready";
 } | {
     status: "pending";
@@ -294,7 +54,7 @@ type InitializeCSRResult = {
  * - `"success"` — the certificate was installed and CRL generated.
  * - `"error"` — the certificate was rejected (see `reason`).
  */
-type InstallCACertificateResult = {
+export type InstallCACertificateResult = {
     status: "success";
 } | {
     status: "error";
@@ -304,7 +64,7 @@ type InstallCACertificateResult = {
 /**
  * Options for creating a {@link CertificateAuthority}.
  */
-interface CertificateAuthorityCoreOptions {
+export interface CertificateAuthorityCoreOptions {
     /** RSA key size for the CA private key. */
     keySize: KeySize;
     /** Filesystem path where the CA directory structure is stored. */
@@ -388,14 +148,42 @@ interface CertificateAuthorityCoreOptions {
      */
     signer?: CaSigner;
 }
-
+/**
+ * An OpenSSL-based Certificate Authority (CA) that can create,
+ * sign, and revoke X.509 certificates.
+ *
+ * The CA maintains a standard OpenSSL directory layout under
+ * {@link CertificateAuthority.rootDir | rootDir}:
+ *
+ * ```
+ * <location>/
+ *   ├── conf/           OpenSSL configuration
+ *   ├── private/        CA private key (cakey.pem)
+ *   ├── public/         CA certificate  (cacert.pem)
+ *   ├── certs/          Signed certificates
+ *   ├── crl/            Revocation lists
+ *   ├── serial          Next serial number
+ *   ├── crlnumber       Next CRL number
+ *   └── index.txt       Certificate database
+ * ```
+ *
+ * @example
+ * ```ts
+ * const ca = new CertificateAuthority({
+ *     keySize: 2048,
+ *     location: "/var/pki/CA"
+ * });
+ * await ca.initialize();
+ * ```
+ */
+export type { IssuedCertificateRecord };
 /**
  * Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
  *
  * All fields are optional. When provided, they override the
  * corresponding values from the CSR.
  */
-interface SignCertificateOptions {
+export interface SignCertificateOptions {
     /** Certificate validity in days (default: 365). */
     validity?: number;
     /**
@@ -427,7 +215,7 @@ interface SignCertificateOptions {
  *
  * @see CertificateAuthority.getCapabilities
  */
-interface PkiBackendCapabilities {
+export interface PkiBackendCapabilities {
     /** Smallest validity this backend can issue, in milliseconds. */
     minValidityMs: number;
     /** Largest validity this backend will issue, in milliseconds. */
@@ -447,7 +235,7 @@ interface PkiBackendCapabilities {
 /**
  * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
  */
-interface GenerateKeyPairAndSignOptions {
+export interface GenerateKeyPairAndSignOptions {
     /** OPC UA application URI (required). */
     applicationUri: string;
     /** X.500 subject for the certificate (e.g. "CN=MyApp"). */
@@ -476,14 +264,14 @@ interface GenerateKeyPairAndSignOptions {
  * Extends the DER options with an optional `passphrase` to protect
  * the PFX bundle.
  */
-interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
+export interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
     /**
      * Passphrase to protect the PFX file.
      * If omitted, the PFX is created without a password.
      */
     passphrase?: string;
 }
-declare class CertificateAuthorityCore {
+export declare class CertificateAuthorityCore {
     #private;
     /** RSA key size used when generating the CA private key. */
     readonly keySize: KeySize;
@@ -902,140 +690,3 @@ declare class CertificateAuthorityCore {
      */
     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, isOpaqueSigner as r, quote as s, resolvePrivateKeyPassphrase as t, CaDatabase as u, type IssuedCertificateRecord as v, configurationFileTemplate as w, defaultSubject as x, escapeOpensslConfDoubleQuoted as y, renderCaConfig as z };