@superhero/eventflow-certificates 4.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Erik Landvall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @superhero/eventflow-certificates
+
+**Version:** 4.0.0
+
+Eventflow Certificates is a TLS certificates management library designed for use within the Eventflow ecosystem. It handles the creation, management, and lifecycle of root, intermediate, and leaf certificates with encryption and secure storage capabilities.
+
+---
+
+## Installation
+
+```bash
+npm install @superhero/eventflow-certificates
+```
+
+---
+
+## Features
+
+- Root, intermediate, and leaf certificate generation
+- Secure encryption and storage of private keys and passwords
+- Automatic certificate renewal upon expiration
+- Configurable encryption algorithms and certificate parameters
+- Lazy-loading with caching to minimize resource usage
+- Easy integration with Eventflow's database layer
+
+---
+
+## Dependencies
+
+- [@superhero/eventflow-db](https://npmjs.com/package/@superhero/eventflow-db)
+- [@superhero/log](https://npmjs.com/package/@superhero/log)
+- [@superhero/openssl](https://npmjs.com/package/@superhero/openssl)
+- [@superhero/deep](https://npmjs.com/package/@superhero/deep)
+
+---
+
+## Usage
+
+### Example
+
+```javascript
+import Certificates from '@superhero/eventflow-certificates';
+import Locator      from '@superhero/locator';
+import Config       from '@superhero/config';
+
+const locator = new Locator();
+const config  = new Config();
+await config.add('@superhero/eventflow-db');
+locator.set('@superhero/config', config);
+
+const db = await locator.lazyload('@superhero/eventflow-db');
+
+const configData = 
+{
+  CERT_PASS_ENCRYPTION_KEY : 'encryptionKey123',
+  CERT_ROOT_DAYS           : 365,
+  CERT_INTERMEDIATE_DAYS   : 30,
+  CERT_LEAF_DAYS           : 7,
+  CERT_ALGORITHM           : 'EdDSA:Ed25519',
+  CERT_HASH                : 'sha256',
+};
+
+const intermediateUID   = 'INTERMEDIATE-CERT-ID';
+const leafUID           = 'LEAF-CERT-ID';
+const certificates      = new Certificates(intermediateUID, leafUID, configData, db);
+const rootCert          = await certificates.root;
+const intermediateCert  = await certificates.intermediate;
+const leafCert          = await certificates.leaf;
+```
+
+---
+
+## Configuration
+
+The `Certificates` class accepts a configuration object with the following properties:
+
+| Property                  | Type     | Description                                                                 |
+|---------------------------|----------|-----------------------------------------------------------------------------|
+| `CERT_PASS_ENCRYPTION_KEY`| `string` | Encryption key used to secure certificate passwords and private keys.       |
+| `CERT_ROOT_DAYS`          | `number` | Validity period of the root certificate in days.                            |
+| `CERT_INTERMEDIATE_DAYS`  | `number` | Validity period of the intermediate certificate in days.                    |
+| `CERT_LEAF_DAYS`          | `number` | Validity period of the leaf certificate in days.                            |
+| `CERT_ALGORITHM`          | `string` | Algorithm used for certificate generation (e.g., `rsa`, `ecdsa`).           |
+| `CERT_HASH`               | `string` | Hash function for certificate signing (e.g., `sha256`, `sha512`).           |
+
+---
+
+## Methods
+
+### Constructor
+
+```javascript
+constructor(intermediateUID, leafUID, config, db)
+```
+
+- **Parameters:**
+  - `intermediateUID`: A unique identifier for the intermediate certificate.
+  - `leafUID`: A unique identifier for the leaf certificate.
+  - `config`: Configuration object.
+  - `db`: Database instance from Eventflow's database layer.
+
+### clearCache
+
+Clears the cached certificates.
+
+```javascript
+clearCache();
+```
+
+### persist
+
+Stores a certificate in the database.
+
+```javascript
+persist(id, validity, cert, key, pass);
+```
+
+- **Parameters:**
+  - `id`: Certificate identifier.
+  - `validity`: Expiration date of the certificate.
+  - `cert`: Certificate content.
+  - `key`: Private key of the certificate.
+  - `pass`: Password for the private key.
+
+### revoke
+
+Revokes a certificate by its ID.
+
+```javascript
+revoke(id);
+```
+
+- **Parameters:**
+  - `id`: Certificate identifier.
+
+### root
+
+Retrieves the root certificate.
+
+```javascript
+const rootCertificate = await certificates.root;
+```
+
+### intermediate
+
+Retrieves the intermediate certificate.
+
+```javascript
+const intermediateCertificate = await certificates.intermediate;
+```
+
+### leaf
+
+Retrieves the leaf certificate.
+
+```javascript
+const leafCertificate = await certificates.leaf;
+```
+
+---
+
+## Testing
+
+Run the test suite with the following command:
+
+```bash
+npm run test-build
+npm test
+```
+
+The test suite includes comprehensive cases to validate functionality, such as:
+
+- Certificate creation and retrieval
+- Cache clearing and lazy loading
+- Certificate expiration handling
+- Error handling for missing configuration
+
+### Test Coverage
+
+```
+▶ @superhero/eventflow-certificates
+  ✔ Throw error if CERT_PASS_ENCRYPTION_KEY is missing in config (2.592666ms)
+
+  ▶ Get root certificate
+    ✔ Get same root certificate each time lazyloading it (0.443311ms)
+
+    ▶ Get intermediate certificate
+      ▶ Get leaf certificate
+        ✔ Clear cache and still get the same certificates (5666.373892ms)
+        ✔ Revoke certificate and regenerate when expired (11.303099ms)
+      ✔ Get leaf certificate (7800.137773ms)
+    ✔ Get intermediate certificate (9664.033522ms)
+  ✔ Get root certificate (11692.320218ms)
+✔ @superhero/eventflow-certificates (11699.129313ms)
+
+tests 7
+suites 1
+pass 7
+
+----------------------------------------------------------------------------------------
+file            | line % | branch % | funcs % | uncovered lines
+----------------------------------------------------------------------------------------
+index.js        |  85.91 |    87.50 |   88.24 | 137-140 154-158 198-204 208-217 220-235
+index.test.js   | 100.00 |   100.00 |  100.00 | 
+----------------------------------------------------------------------------------------
+all files       |  89.83 |    91.67 |   92.86 | 
+----------------------------------------------------------------------------------------
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+## Contributing
+
+Feel free to submit issues or pull requests for improvements or additional features.

package/index.js

@@ -0,0 +1,298 @@
+import crypto     from 'node:crypto'
+import Log        from '@superhero/log'
+import OpenSSL    from '@superhero/openssl'
+import deepassign from '@superhero/deep/assign'
+
+/**
+ * @memberof Eventflow
+ */
+export default class Certificates
+{
+  #db
+  log     = new Log({ label: '[EVENTFLOW:CERTIFICATES]' })
+  #map    = new Map()
+  openSSL = new OpenSSL()
+  config  =
+  {
+    CERT_ALGORITHM              : OpenSSL.ALGO.EdDSAEd448,
+    CERT_HASH                   : OpenSSL.HASH.SHA512,
+    CERT_ROOT_DAYS              : 365,
+    CERT_INTERMEDIATE_DAYS      : 30,
+    CERT_LEAF_DAYS              : 7,
+    CERT_PASS_CIPHER            : 'aes-256-gcm',
+    CERT_PASS_PBKDF2_HASH       : 'sha512',
+    CERT_PASS_PBKDF2_BYTES      : 32,
+    CERT_PASS_PBKDF2_ITERATIONS : 1e6
+  }
+
+  constructor(intermediateUID, leafUID, config, db)
+  {
+    this.intermediateUID  = intermediateUID
+    this.leafUID          = leafUID
+    this.#db              = db
+
+    deepassign(this.config, config)
+
+    if(false === !!this.config.CERT_PASS_ENCRYPTION_KEY)
+    {
+      const error = new Error('missing configured certification password encryption key')
+      error.code  = 'E_EVENTFLOW_CERTIFICATES_MISSING_CONFIGURATION'
+      error.cause = 'The encryption key is required to encrypt and decrypt the certificates password and private key'
+      throw error
+    }
+  }
+
+  clearCache()
+  {
+    this.#map.clear()
+  }
+
+  /**
+   * Persist a specific certificate by ID in the database.
+   * 
+   * @param {string} id       the certificate identifier
+   * @param {string} validity the validity expiration date of the certificate
+   * @param {string} cert     the certificate
+   * @param {string} key      the certificate private key
+   * @param {string} pass     the certificate private key password
+   * 
+   * @returns {Promise<boolean>} true if the certificate was persisted, false if it already exists
+   */
+  perist(id, validity, cert, key, pass)
+  {
+    const
+      encryptionKey = this.config.CERT_PASS_ENCRYPTION_KEY,
+      encryptedKey  = this.#encrypt(encryptionKey, key),
+      encryptedPass = this.#encrypt(encryptionKey, pass)
+
+    return this.#db.persistCertificate(
+    {
+      id,
+      validity,
+      cert,
+      // Encrypted Certificate Private Key
+      key       : encryptedKey.encrypted,
+      key_salt  : encryptedKey.salt,
+      key_iv    : encryptedKey.iv,
+      key_tag   : encryptedKey.tag,
+      // Encrypted Certificate Private Key Password
+      pass      : encryptedPass.encrypted,
+      pass_salt : encryptedPass.salt,
+      pass_iv   : encryptedPass.iv,
+      pass_tag  : encryptedPass.tag
+    })
+  }
+
+  /**
+   * Revoke a specific certificate by ID in the database.
+   * @param {string} id the certificate identifier
+   * @returns {Promise<boolean>} true if the certificate was revoked, false if it does not exist
+   */
+  revoke(id)
+  {
+    return this.#db.revokeCertificate(id)
+  }
+
+  /**
+   * The root certificate authority (CA).
+   * @returns {Promise<{cert:string, key:string, pass:string}>}
+   */
+  get root()
+  {
+    return this.#lazyload('EVENTFLOW-ROOT-CA', this.#createRoot.bind(this))
+  }
+
+  /**
+   * The intermediate certificate authority (ICA).
+   * @returns {Promise<{cert:string, key:string, pass:string}>}
+   */
+  get intermediate()
+  {
+    return this.#lazyload(this.intermediateUID, this.#createIntermediate.bind(this))
+  }
+
+  /**
+   * The leaf end-entity certificate.
+   * @returns {Promise<{cert:string, key:string, pass:string}>}
+   */
+  get leaf()
+  {
+    return this.#lazyload(this.leafUID, this.#createLeaf.bind(this))
+  }
+
+  async #lazyload(id, factory)
+  {
+    if(false === this.#map.has(id))
+    {
+      try
+      {
+        this.#map.set(id, await this.#readCertificate(id))
+      }
+      catch(error)
+      {
+        if('E_EVENTFLOW_DB_CERTIFICATE_NOT_FOUND' === error.code)
+        {
+          this.#map.set(id, await this.#eagerload(id, factory))
+        }
+        else
+        {
+          throw error
+        }
+      }
+
+      this.log.info`certificate loaded ${id}`
+    }
+
+    const crt = this.#map.get(id)
+
+    // If the certificate is expired, then revoke it and create a new one.
+    // 10 minutes before expiration, the certificate is considered expired
+    // to prevent the certificate from being validated during a borderline
+    // expiration.
+    if(Date.now() + 6e5 > crt.validity)
+    {
+      this.log.warn`certificate expired ${id}`
+      this.#map.delete(id)
+      await this.#db.revokeCertificate(id)
+      return this.#lazyload(id, factory)
+    }
+    else
+    {
+      return crt
+    }
+  }
+
+  async #readCertificate(id)
+  {
+    const { cert,     key,  key_iv,  key_salt,  key_tag, 
+            validity, pass, pass_iv, pass_salt, pass_tag } = await this.#db.readCertificate(id)
+    const
+      encryptionKey = this.config.CERT_PASS_ENCRYPTION_KEY,
+      encryptedPass = { encrypted:pass, salt:pass_salt, iv:pass_iv, tag:pass_tag },
+      encryptedKey  = { encrypted:key,  salt:key_salt,  iv:key_iv,  tag:key_tag  },
+      decryptedPass = this.#decrypt(encryptionKey, encryptedPass),
+      decryptedKey  = this.#decrypt(encryptionKey, encryptedKey)
+
+    return { validity, cert, key:decryptedKey, pass:decryptedPass }
+  }
+
+  async #eagerload(id, factory)
+  {
+    const
+      keyPass       = this.#generateRandomPassword(),
+      certificate   = await factory(id, keyPass)
+
+    const { cert, key } = certificate
+    const
+      x509          = new crypto.X509Certificate(certificate.cert),
+      validity      = x509.validToDate,
+      isPersisted   = await this.perist(id, validity, cert, key, keyPass)
+
+    // If multiple replicas tries at the same time to creater the certificate, 
+    // then only the first one to persist is valid, the rest should throw away 
+    // the work they done and instead read what is persisted in the database.
+    if(isPersisted)
+    {
+      return { validity, cert, key, pass:keyPass }
+    }
+    else
+    {
+      // If the certificate was not persisted, then it was already created 
+      // by another replica. We should then read the persisted certificate
+      // from the database, and return it instead of what has been generated.
+      return await this.#readCertificate(id)
+    }
+  }
+
+  #createRoot(UID, password)
+  {
+    return this.openSSL.root(
+    {
+      days      : this.config.CERT_ROOT_DAYS,
+      algorithm : this.config.CERT_ALGORITHM,
+      hash      : this.config.CERT_HASH,
+      subject   : { UID },
+      password
+    })
+  }
+
+  async #createIntermediate(UID, password)
+  {
+    const root = await this.root
+    return await this.openSSL.intermediate(root, 
+    {
+      days      : this.config.CERT_INTERMEDIATE_DAYS,
+      algorithm : this.config.CERT_ALGORITHM,
+      hash      : this.config.CERT_HASH,
+      dns       : [ '.' + UID ],
+      subject   : { UID },
+      password  :
+      {
+        input   : root.pass,
+        output  : password
+      }
+    })
+  }
+
+  async #createLeaf(UID, password)
+  {
+    const ica = await this.intermediate
+    return await this.openSSL.leaf(ica,
+    {
+      days      : this.config.CERT_LEAF_DAYS,
+      algorithm : this.config.CERT_ALGORITHM,
+      hash      : this.config.CERT_HASH,
+      dns       : [ this.leafUID ],
+      subject   : { UID },
+      password  :
+      {
+        input   : ica.pass,
+        output  : password
+      }
+    })
+  }
+
+  #encrypt(password, decrypted)
+  {
+    const
+      cipher      = this.config.CERT_PASS_CIPHER,
+      hash        = this.config.CERT_PASS_PBKDF2_HASH,
+      bytes       = this.config.CERT_PASS_PBKDF2_BYTES,
+      iterations  = this.config.CERT_PASS_PBKDF2_ITERATIONS,
+      salt        = crypto.randomBytes(16),
+      iv          = crypto.randomBytes(16),
+      key         = crypto.pbkdf2Sync(password, salt, iterations, bytes, hash), // derive key
+      cipheriv    = crypto.createCipheriv(cipher, key, iv),
+      encrypted   = Buffer.concat([ cipheriv.update(decrypted, 'utf8'), cipheriv.final() ]),
+      tag         = cipheriv.getAuthTag() // helps identify corruption
+
+    return { encrypted, salt, iv, tag }
+  }
+
+  #decrypt(password, { encrypted, salt, iv, tag })
+  {
+    const
+      cipher      = this.config.CERT_PASS_CIPHER,
+      hash        = this.config.CERT_PASS_PBKDF2_HASH,
+      bytes       = this.config.CERT_PASS_PBKDF2_BYTES,
+      iterations  = this.config.CERT_PASS_PBKDF2_ITERATIONS,
+      key         = crypto.pbkdf2Sync(password, salt, iterations, bytes, hash),
+      decipher    = crypto.createDecipheriv(cipher, key, iv)
+
+    decipher.setAuthTag(tag)
+  
+    const decrypted = Buffer.concat([ decipher.update(encrypted), decipher.final() ])
+    return decrypted.toString('utf8')
+  }
+
+  #generateRandomPassword()
+  {
+    const
+      length  = crypto.randomInt(64, 128),
+      random  = crypto.randomBytes(length),
+      ascii   = random.toString('latin1'),
+      nonNull = ascii.replaceAll('\x00', '').replaceAll('$', '')
+
+    return nonNull
+  }
+}

package/index.test.js

@@ -0,0 +1,115 @@
+import Config               from '@superhero/config'
+import Locator              from '@superhero/locator'
+import Certificates         from '@superhero/eventflow-certificates'
+import assert               from 'node:assert/strict'
+import { X509Certificate }  from 'node:crypto'
+import { suite, test, before, after } from 'node:test'
+
+suite('@superhero/eventflow-certificates', async () =>
+{
+  const 
+    config  = new Config(),
+    locator = new Locator()
+
+  await config.add('@superhero/eventflow-db')
+  locator.set('@superhero/config', config)
+  const db = await locator.lazyload('@superhero/eventflow-db')
+
+  let conf, manager, icaUID = 'INTERMEDIATE-CERT-ID', leafUID = 'LEAF-CERT-ID'
+
+  before(() =>
+  {
+    conf =
+    {
+      CERT_PASS_ENCRYPTION_KEY  : 'encryptionKey123',
+      CERT_ROOT_DAYS            : 365,
+      CERT_INTERMEDIATE_DAYS    : 30,
+      CERT_LEAF_DAYS            : 7,
+      CERT_ALGORITHM            : 'rsa',
+      CERT_HASH                 : 'sha256'
+    }
+
+    manager = new Certificates(icaUID, leafUID, conf, db)
+    manager.log.config.mute = true
+  })
+
+  after(() => db.close())
+
+  test('Throw error if CERT_PASS_ENCRYPTION_KEY is missing in config', () =>
+  {
+    delete conf.CERT_PASS_ENCRYPTION_KEY
+    assert.throws(
+      () => new Certificates(icaUID, leafUID, conf, db), 
+      { code: 'E_EVENTFLOW_CERTIFICATES_MISSING_CONFIGURATION' })
+  })
+
+  test('Get root certificate', async (sub) =>
+  {
+    const root = await manager.root
+
+    assert.ok(root.validity > Date.now())
+    assert.ok(root.cert)
+    assert.ok(root.key)
+    assert.ok(root.pass)
+
+    const rootX509 = new X509Certificate(root.cert)
+    assert.ok(rootX509.checkIssued(rootX509))
+
+    await sub.test('Get same root certificate each time lazyloading it', async () =>
+    {
+      const root2 = await manager.root
+      assert.deepEqual(root, root2)
+    })
+
+    await sub.test('Get intermediate certificate', async (sub) =>
+    {
+      const ica = await manager.intermediate
+  
+      assert.ok(ica.validity > Date.now())
+      assert.ok(ica.cert)
+      assert.ok(ica.key)
+      assert.ok(ica.pass)
+  
+      const icaX509 = new X509Certificate(ica.cert)
+      assert.ok(icaX509.checkIssued(rootX509))
+
+      await sub.test('Get leaf certificate', async (sub) =>
+      {
+        const leaf = await manager.leaf
+    
+        assert.ok(leaf.validity > Date.now())
+        assert.ok(leaf.cert)
+        assert.ok(leaf.key)
+        assert.ok(leaf.pass)
+    
+        const leafX509 = new X509Certificate(leaf.cert)
+        assert.ok(leafX509.checkIssued(icaX509))
+
+        await sub.test('Clear cache and still get the same certificates', async (sub) =>
+        {
+          manager.clearCache()
+
+          const
+            root2 = await manager.root,
+            ica2  = await manager.intermediate,
+            leaf2 = await manager.leaf
+
+          assert.deepEqual(root, root2)
+          assert.deepEqual(ica, ica2)
+          assert.deepEqual(leaf, leaf2)
+        })
+
+        await sub.test('Revoke certificate and regenerate when expired', async () =>
+        {
+          await assert.doesNotReject(manager.revoke(leafUID))
+
+          const
+            leaf      = await manager.leaf,
+            leafX509  = new X509Certificate(leaf.cert)
+
+          assert.ok(leafX509.checkIssued(icaX509))
+        })
+      })
+    })
+  })
+})

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@superhero/eventflow-certificates",
+  "version": "4.0.0",
+  "description": "Eventflow certificates is common tls certificates logic used in the eventflow ecosystem.",
+  "keywords": [
+    "eventflow"
+  ],
+  "main": "index.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "dependencies": {
+    "@superhero/eventflow-db": "^4.1.0",
+    "@superhero/log": "^4.0.0",
+    "@superhero/openssl": "^4.0.2",
+    "@superhero/deep": "^4.1.0"
+  },
+  "devDependencies": {
+    "@superhero/config": "^4.1.2",
+    "@superhero/locator": "^4.2.0"
+  },
+  "scripts": {
+    "test-build": "npm explore @superhero/eventflow-db -- npm run test-build",
+    "test-only": "node --test-only --trace-warnings --test --experimental-test-coverage",
+    "test": "node --test --experimental-test-coverage"
+  },
+  "author": {
+    "name": "Erik Landvall",
+    "email": "erik@landvall.se"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superhero/eventflow-certificates.git"
+  }
+}