@postalsys/certs 1.0.12 → 1.0.14

package/.github/workflows/release.yaml

@@ -18,7 +18,7 @@ jobs:
               with:
                   release-type: node
                   package-name: ${{vars.NPM_MODULE_NAME}}
-                  pull-request-title-pattern: 'chore${scope}: release ${version} [skip-ci]'
+                  pull-request-title-pattern: "chore${scope}: release ${version} [skip-ci]"
             # The logic below handles the npm publication:
             - uses: actions/checkout@v3
               # these if statements ensure that a publication only occurs when
@@ -26,12 +26,10 @@ jobs:
               if: ${{ steps.release.outputs.release_created }}
             - uses: actions/setup-node@v3
               with:
-                  node-version: 18
-                  registry-url: 'https://registry.npmjs.org'
+                  node-version: 24
+                  registry-url: "https://registry.npmjs.org"
               if: ${{ steps.release.outputs.release_created }}
             - run: npm ci
               if: ${{ steps.release.outputs.release_created }}
             - run: npm publish --provenance --access public
-              env:
-                  NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
               if: ${{ steps.release.outputs.release_created }}

package/.github/workflows/test.yaml

@@ -0,0 +1,21 @@
+on:
+    push:
+        branches:
+            - master
+    pull_request:
+
+name: test
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                node-version: [20, 22, 24]
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: npm
+            - run: npm ci
+            - run: npm test

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [1.0.14](https://github.com/postalsys/certs/compare/v1.0.13...v1.0.14) (2026-03-23)
+
+
+### Bug Fixes
+
+* add test suite and CI workflow ([1c5569c](https://github.com/postalsys/certs/commit/1c5569c02386e8ed167672a78980e6f621a8db4a))
+* bumped deps ([2673ff0](https://github.com/postalsys/certs/commit/2673ff0db815f0b33b060afba3f9cdfe035cbd44))
+* update test matrix to Node 20, 22, 24 ([c20356b](https://github.com/postalsys/certs/commit/c20356b27e8c5e648657c404c57f22375ded0d42))
+
+## [1.0.13](https://github.com/postalsys/certs/compare/v1.0.12...v1.0.13) (2026-03-23)
+
+
+### Bug Fixes
+
+* bumped deos ([3d8cc4c](https://github.com/postalsys/certs/commit/3d8cc4ce6f5a58c25f9780076dc8adc99f26d279))
+* update release workflow to Node 24 and use trusted publishers ([2392f54](https://github.com/postalsys/certs/commit/2392f547f421bbf83f32ffe4e06cbbf3f4cfc80c))
+
 ## [1.0.12](https://github.com/postalsys/certs/compare/v1.0.11...v1.0.12) (2025-09-29)
 
 

package/README.md

@@ -0,0 +1,122 @@
+# @postalsys/certs
+
+Manage Let's Encrypt SSL/TLS certificates with automatic acquisition, renewal, and storage via the ACME protocol. Certificates and ACME account data are stored in Redis. Supports ACME HTTP-01 challenges.
+
+## Installation
+
+```
+npm install @postalsys/certs
+```
+
+**Requirements:** Node.js 15+ (for CAA record validation), Redis
+
+## Usage
+
+```js
+const Redis = require('ioredis');
+const express = require('express');
+const { Certs } = require('@postalsys/certs');
+
+const redis = new Redis();
+const app = express();
+
+const certs = new Certs({
+    redis,
+    namespace: 'myapp',
+
+    acme: {
+        // Use 'production' and the production directory URL for real certificates
+        environment: 'production',
+        directoryUrl: 'https://acme-v02.api.letsencrypt.org/directory',
+        email: 'admin@example.com'
+    },
+
+    // Optional: encrypt private keys before storing in Redis
+    encryptFn: async (value) => {
+        // your encryption logic
+        return encryptedValue;
+    },
+    decryptFn: async (value) => {
+        // your decryption logic
+        return decryptedValue;
+    }
+});
+
+// Retrieve or acquire a certificate
+const certData = await certs.getCertificate('example.com');
+// certData.cert - PEM certificate
+// certData.privateKey - PEM private key
+// certData.ca - array of CA chain certificates
+// certData.validTo - expiration date
+
+// ACME HTTP-01 challenge handler
+app.get('/.well-known/acme-challenge/:token', (req, res) => {
+    const token = req.params.token;
+    const domain = req.get('host');
+    certs
+        .routeHandler(domain, token)
+        .then(challenge => {
+            res.status(200).set('content-type', 'text/plain').send(challenge);
+        })
+        .catch(err => {
+            res.status(err.responseCode || 500).send({
+                error: err.message,
+                code: err.code
+            });
+        });
+});
+```
+
+## Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `redis` | Object | *required* | ioredis (or compatible) client instance |
+| `namespace` | String | `undefined` | Key prefix for Redis storage |
+| `encryptFn` | Function | identity | Async function to encrypt private keys before storage |
+| `decryptFn` | Function | identity | Async function to decrypt private keys after retrieval |
+| `acme.environment` | String | `'development'` | `'development'` (staging) or `'production'` |
+| `acme.directoryUrl` | String | LE staging URL | ACME directory URL |
+| `acme.email` | String | | Subscriber email for the ACME account |
+| `acme.caaDomains` | Array | `['letsencrypt.org']` | Allowed CAA record domains |
+| `acme.keyBits` | Number | `2048` | RSA key size for ACME account key |
+| `acme.keyExponent` | Number | `65537` | RSA public exponent for ACME account key |
+| `keyBits` | Number | `2048` | RSA key size for domain certificates |
+| `keyExponent` | Number | `65537` | RSA public exponent for domain certificates |
+| `logger` | Object | pino instance | Logger (pino-compatible) |
+
+## API
+
+### `Certs.create(options)`
+
+Static factory method. Returns a new `Certs` instance.
+
+### `getCertificate(domain, skipAcquire?)`
+
+Returns stored certificate data for the domain. If the certificate is missing or expired, automatically acquires a new one via ACME unless `skipAcquire` is `true`.
+
+Returns an object with `cert`, `privateKey`, `ca`, `validFrom`, `validTo`, `altNames`, `serialNumber`, `fingerprint`, `status`, and `lastError`, or `false` if no certificate exists.
+
+### `acquireCert(domain)`
+
+Forces certificate acquisition or renewal for the domain. Validates the domain name and CAA records, obtains a distributed lock, generates a CSR, and requests a certificate via ACME HTTP-01 challenge. Falls back to existing certificate data on error.
+
+### `routeHandler(domain, token)`
+
+Resolves an ACME HTTP-01 challenge. Use this as the handler for `GET /.well-known/acme-challenge/:token` requests. Returns the `keyAuthorization` string on success or throws with a `responseCode` property on failure.
+
+### `listCertificateDomains()`
+
+Returns a sorted array of all domain names that have certificate records.
+
+### `deleteCertificateData(domain)`
+
+Removes all stored certificate data for the domain.
+
+## Automatic Renewal
+
+Certificates are automatically renewed when retrieved via `getCertificate()` if they expire within 30 days. After a failed renewal attempt, a short safety lock prevents repeated retries.
+
+## License
+
+ISC

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@postalsys/certs",
-    "version": "1.0.12",
+    "version": "1.0.14",
     "description": "Manage Let's Encrypt certificates",
     "main": "lib/certs.js",
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1",
+        "test": "node --test --test-force-exit test/*.test.js",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install"
     },
     "keywords": [],
@@ -21,15 +21,15 @@
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "9.1.0",
         "express": "4.19.2",
-        "ioredis": "5.8.0"
+        "ioredis": "5.10.1"
     },
     "dependencies": {
         "@root/acme": "3.1.0",
-        "ioredfour": "1.3.0-ioredis-07",
-        "joi": "18.0.1",
+        "ioredfour": "1.4.1",
+        "joi": "18.0.2",
         "msgpack5": "6.0.2",
         "pem-jwk": "2.0.0",
-        "pino": "9.12.0",
+        "pino": "10.3.1",
         "punycode.js": "2.3.1"
     }
 }

package/test/acme-challenge.test.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const { describe, it, beforeEach } = require('node:test');
+const assert = require('node:assert/strict');
+const AcmeChallenge = require('../lib/acme-challenge');
+const { createMockRedis } = require('./helpers/mock-redis');
+
+describe('AcmeChallenge', () => {
+    let redis;
+    let challenge;
+
+    beforeEach(() => {
+        redis = createMockRedis();
+        challenge = AcmeChallenge.create({ redis, namespace: 'test', ttl: 5000 });
+    });
+
+    describe('create', () => {
+        it('should return an AcmeChallenge instance', () => {
+            assert.ok(challenge instanceof AcmeChallenge);
+        });
+
+        it('should generate a uuid', () => {
+            assert.ok(challenge.uuid);
+            assert.equal(typeof challenge.uuid, 'string');
+        });
+
+        it('should use default TTL when not specified', () => {
+            const c = AcmeChallenge.create({ redis });
+            assert.equal(c.ttl, 2 * 3600 * 1000);
+        });
+    });
+
+    describe('init', () => {
+        it('should return null', () => {
+            assert.equal(challenge.init(), null);
+        });
+    });
+
+    describe('getKey', () => {
+        it('should prefix with namespace', () => {
+            assert.equal(challenge.getKey('foo'), 'test:certs:foo');
+        });
+
+        it('should work without namespace', () => {
+            const c = AcmeChallenge.create({ redis });
+            assert.equal(c.getKey('foo'), 'certs:foo');
+        });
+    });
+
+    describe('setData and getData', () => {
+        it('should roundtrip challenge data', async () => {
+            const data = { acme: { token: 'tok', secret: { value: 'auth123' } } };
+            await challenge.setData('example.com', 'tok', data);
+            const result = await challenge.getData('example.com', 'tok');
+            assert.deepEqual(result, data);
+        });
+
+        it('should return false for non-existent data', async () => {
+            const result = await challenge.getData('missing.com', 'notoken');
+            assert.equal(result, false);
+        });
+    });
+
+    describe('deleteData', () => {
+        it('should delete stored data', async () => {
+            await challenge.setData('example.com', 'tok', { test: true });
+            await challenge.deleteData('example.com', 'tok');
+            const result = await challenge.getData('example.com', 'tok');
+            assert.equal(result, false);
+        });
+    });
+
+    describe('set', () => {
+        it('should store challenge when domain exists in settings', async () => {
+            await challenge.settings.set('domain:example.com:data', { domain: 'example.com' });
+
+            await challenge.set({
+                challenge: {
+                    altname: 'example.com',
+                    keyAuthorization: 'auth-value-123',
+                    token: 'challenge-token'
+                }
+            });
+
+            const data = await challenge.getData('example.com', 'challenge-token');
+            assert.ok(data);
+            assert.equal(data.acme.secret.value, 'auth-value-123');
+        });
+
+        it('should throw 404 if domain not in settings', async () => {
+            await assert.rejects(
+                () =>
+                    challenge.set({
+                        challenge: {
+                            altname: 'unknown.com',
+                            keyAuthorization: 'auth',
+                            token: 'tok'
+                        }
+                    }),
+                err => {
+                    assert.equal(err.responseCode, 404);
+                    return true;
+                }
+            );
+        });
+    });
+
+    describe('get', () => {
+        it('should return keyAuthorization for valid challenge', async () => {
+            await challenge.settings.set('domain:example.com:data', { domain: 'example.com' });
+            await challenge.set({
+                challenge: {
+                    altname: 'example.com',
+                    keyAuthorization: 'my-auth-key',
+                    token: 'my-token'
+                }
+            });
+
+            const result = await challenge.get({
+                challenge: {
+                    identifier: { value: 'example.com' },
+                    token: 'my-token'
+                }
+            });
+
+            assert.ok(result);
+            assert.equal(result.keyAuthorization, 'my-auth-key');
+        });
+
+        it('should return null for non-existent challenge', async () => {
+            const result = await challenge.get({
+                challenge: {
+                    identifier: { value: 'missing.com' },
+                    token: 'notoken'
+                }
+            });
+            assert.equal(result, null);
+        });
+
+        it('should return null and delete expired challenge', async () => {
+            // Manually insert expired challenge data
+            await challenge.setData('example.com', 'expired-tok', {
+                acme: {
+                    token: 'expired-tok',
+                    secret: {
+                        value: 'old-auth',
+                        created: new Date(Date.now() - 10000),
+                        expires: new Date(Date.now() - 1000)
+                    }
+                }
+            });
+
+            const result = await challenge.get({
+                challenge: {
+                    identifier: { value: 'example.com' },
+                    token: 'expired-tok'
+                }
+            });
+
+            assert.equal(result, null);
+
+            // Verify it was deleted
+            const data = await challenge.getData('example.com', 'expired-tok');
+            assert.equal(data, false);
+        });
+
+        it('should return null for challenge with missing secret', async () => {
+            await challenge.setData('example.com', 'bad-tok', {
+                acme: { token: 'bad-tok' }
+            });
+
+            const result = await challenge.get({
+                challenge: {
+                    identifier: { value: 'example.com' },
+                    token: 'bad-tok'
+                }
+            });
+
+            assert.equal(result, null);
+        });
+    });
+
+    describe('remove', () => {
+        it('should delete challenge data', async () => {
+            await challenge.setData('example.com', 'rm-tok', { acme: { token: 'rm-tok' } });
+
+            await challenge.remove({
+                challenge: {
+                    identifier: { value: 'example.com' },
+                    token: 'rm-tok'
+                }
+            });
+
+            const data = await challenge.getData('example.com', 'rm-tok');
+            assert.equal(data, false);
+        });
+    });
+});

package/test/certs.test.js

@@ -0,0 +1,277 @@
+'use strict';
+
+const { describe, it, beforeEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { Certs } = require('../lib/certs');
+const { createMockRedis } = require('./helpers/mock-redis');
+
+describe('Certs', () => {
+    let redis;
+
+    beforeEach(() => {
+        redis = createMockRedis();
+    });
+
+    describe('create', () => {
+        it('should return a Certs instance', () => {
+            const certs = Certs.create({ redis });
+            assert.ok(certs instanceof Certs);
+        });
+    });
+
+    describe('constructor defaults', () => {
+        it('should set default acme options', () => {
+            const certs = new Certs({ redis });
+            assert.equal(certs.acmeOptions.environment, 'development');
+            assert.ok(certs.acmeOptions.directoryUrl.includes('staging'));
+            assert.deepEqual(certs.acmeOptions.caaDomains, ['letsencrypt.org']);
+        });
+
+        it('should set default key parameters', () => {
+            const certs = new Certs({ redis });
+            assert.equal(certs.keyBits, 2048);
+            assert.equal(certs.keyExponent, 65537);
+        });
+
+        it('should use identity functions for encrypt/decrypt by default', async () => {
+            const certs = new Certs({ redis });
+            assert.equal(await certs.encryptFn('test'), 'test');
+            assert.equal(await certs.decryptFn('test'), 'test');
+        });
+
+        it('should accept custom encrypt/decrypt functions', async () => {
+            const certs = new Certs({
+                redis,
+                encryptFn: async v => 'enc:' + v,
+                decryptFn: async v => v.replace('enc:', '')
+            });
+            assert.equal(await certs.encryptFn('hello'), 'enc:hello');
+            assert.equal(await certs.decryptFn('enc:hello'), 'hello');
+        });
+
+        it('should accept custom key parameters', () => {
+            const certs = new Certs({ redis, keyBits: 4096, keyExponent: 3 });
+            assert.equal(certs.keyBits, 4096);
+            assert.equal(certs.keyExponent, 3);
+        });
+
+        it('should normalize caaDomains to array', () => {
+            const certs = new Certs({ redis, acme: { caaDomains: 'letsencrypt.org' } });
+            assert.ok(Array.isArray(certs.acmeOptions.caaDomains));
+        });
+    });
+
+    describe('getKey', () => {
+        it('should prefix with namespace', () => {
+            const certs = new Certs({ redis, namespace: 'myns' });
+            assert.equal(certs.getKey('certlist'), 'myns:certs:certlist');
+        });
+
+        it('should work without namespace', () => {
+            const certs = new Certs({ redis });
+            assert.equal(certs.getKey('certlist'), 'certs:certlist');
+        });
+    });
+
+    describe('validateDomain', () => {
+        it('should accept valid domains', async () => {
+            const certs = new Certs({ redis, acme: { caaDomains: [] } });
+            const result = await certs.validateDomain('example.com');
+            assert.equal(result, true);
+        });
+
+        it('should reject invalid domain names', async () => {
+            const certs = new Certs({ redis });
+            await assert.rejects(() => certs.validateDomain('not a domain!'), err => {
+                assert.equal(err.responseCode, 400);
+                assert.equal(err.code, 'invalid_domain');
+                return true;
+            });
+        });
+
+        it('should reject empty domain', async () => {
+            const certs = new Certs({ redis });
+            await assert.rejects(() => certs.validateDomain(''), err => {
+                assert.equal(err.responseCode, 400);
+                return true;
+            });
+        });
+    });
+
+    describe('routeHandler', () => {
+        it('should reject invalid domain', async () => {
+            const certs = new Certs({ redis });
+            await assert.rejects(() => certs.routeHandler('not valid!', 'token123'), err => {
+                assert.equal(err.responseCode, 400);
+                assert.equal(err.code, 'InputValidationError');
+                return true;
+            });
+        });
+
+        it('should reject empty token', async () => {
+            const certs = new Certs({ redis });
+            await assert.rejects(() => certs.routeHandler('example.com', ''), err => {
+                assert.equal(err.responseCode, 400);
+                return true;
+            });
+        });
+
+        it('should reject token exceeding max length', async () => {
+            const certs = new Certs({ redis });
+            const longToken = 'a'.repeat(257);
+            await assert.rejects(() => certs.routeHandler('example.com', longToken), err => {
+                assert.equal(err.responseCode, 400);
+                return true;
+            });
+        });
+
+        it('should return keyAuthorization for valid challenge', async () => {
+            const certs = new Certs({ redis, namespace: 'rt' });
+
+            await certs.settings.set('domain:example.com:data', { domain: 'example.com' });
+            await certs.acmeChallenge.set({
+                challenge: {
+                    altname: 'example.com',
+                    keyAuthorization: 'the-auth-key',
+                    token: 'the-token'
+                }
+            });
+
+            const result = await certs.routeHandler('example.com', 'the-token');
+            assert.equal(result, 'the-auth-key');
+        });
+
+        it('should throw 404 for unknown challenge', async () => {
+            const certs = new Certs({ redis });
+            await assert.rejects(() => certs.routeHandler('example.com', 'unknown'), err => {
+                assert.equal(err.responseCode, 404);
+                assert.equal(err.code, 'ChallengeNotFound');
+                return true;
+            });
+        });
+    });
+
+    describe('listCertificateDomains', () => {
+        it('should return empty array when no domains', async () => {
+            const certs = new Certs({ redis });
+            const result = await certs.listCertificateDomains();
+            assert.deepEqual(result, []);
+        });
+
+        it('should return sorted domains', async () => {
+            const certs = new Certs({ redis, namespace: 'list' });
+            const key = certs.getKey('certlist');
+            await redis.sadd(key, 'zebra.com');
+            await redis.sadd(key, 'alpha.com');
+            await redis.sadd(key, 'mid.com');
+
+            const result = await certs.listCertificateDomains();
+            assert.deepEqual(result, ['alpha.com', 'mid.com', 'zebra.com']);
+        });
+    });
+
+    describe('setCertificateData and loadCertificateData', () => {
+        it('should store and load certificate data', async () => {
+            const certs = new Certs({ redis, namespace: 'data' });
+
+            await certs.setCertificateData('example.com', {
+                domain: 'example.com',
+                cert: '---PEM---',
+                ca: ['---CA---'],
+                privateKey: 'privkey',
+                status: 'valid',
+                validFrom: new Date('2025-01-01'),
+                validTo: new Date('2026-01-01'),
+                lastCheck: new Date(),
+                lastError: null
+            });
+
+            const loaded = await certs.loadCertificateData('example.com');
+            assert.ok(loaded);
+            assert.equal(loaded.cert, '---PEM---');
+            assert.equal(loaded.privateKey, 'privkey');
+            assert.equal(loaded.status, 'valid');
+        });
+
+        it('should return false for non-existent domain', async () => {
+            const certs = new Certs({ redis, namespace: 'miss' });
+            const result = await certs.loadCertificateData('missing.com');
+            assert.equal(result, false);
+        });
+
+        it('should encrypt private key on store and decrypt on load', async () => {
+            const certs = new Certs({
+                redis,
+                namespace: 'enc',
+                encryptFn: async v => (v ? 'ENC:' + v : v),
+                decryptFn: async v => (v && typeof v === 'string' ? v.replace('ENC:', '') : v)
+            });
+
+            await certs.setCertificateData('example.com', {
+                domain: 'example.com',
+                privateKey: 'mysecretkey',
+                status: 'pending'
+            });
+
+            const loaded = await certs.loadCertificateData('example.com');
+            assert.ok(loaded);
+            assert.equal(loaded.privateKey, 'mysecretkey');
+        });
+    });
+
+    describe('deleteCertificateData', () => {
+        it('should delete certificate data', async () => {
+            const certs = new Certs({ redis, namespace: 'del' });
+
+            await certs.setCertificateData('example.com', {
+                domain: 'example.com',
+                cert: 'cert',
+                status: 'valid'
+            });
+
+            await certs.deleteCertificateData('example.com');
+            const result = await certs.loadCertificateData('example.com');
+            assert.equal(result, false);
+        });
+    });
+
+    describe('getCertificate', () => {
+        it('should return valid certificate data', async () => {
+            const certs = new Certs({ redis, namespace: 'gc' });
+
+            await certs.setCertificateData('example.com', {
+                domain: 'example.com',
+                cert: 'certpem',
+                status: 'valid',
+                validFrom: new Date('2025-01-01'),
+                validTo: new Date('2027-01-01')
+            });
+
+            const result = await certs.getCertificate('example.com', true);
+            assert.ok(result);
+            assert.equal(result.cert, 'certpem');
+        });
+
+        it('should return false with skipAcquire when no certificate exists', async () => {
+            const certs = new Certs({ redis, namespace: 'skip' });
+            const result = await certs.getCertificate('missing.com', true);
+            assert.equal(result, false);
+        });
+
+        it('should return existing data with skipAcquire even if expired', async () => {
+            const certs = new Certs({ redis, namespace: 'exp' });
+
+            await certs.setCertificateData('example.com', {
+                domain: 'example.com',
+                cert: 'oldcert',
+                status: 'valid',
+                validFrom: new Date('2020-01-01'),
+                validTo: new Date('2021-01-01')
+            });
+
+            const result = await certs.getCertificate('example.com', true);
+            assert.ok(result);
+            assert.equal(result.cert, 'oldcert');
+        });
+    });
+});

package/test/helpers/mock-redis.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const msgpack = require('msgpack5')();
+
+function createMockRedis() {
+    const hashes = new Map();
+    const keys = new Map();
+    const sets = new Map();
+
+    function getHash(key) {
+        if (!hashes.has(key)) {
+            hashes.set(key, new Map());
+        }
+        return hashes.get(key);
+    }
+
+    function getSet(key) {
+        if (!sets.has(key)) {
+            sets.set(key, new Set());
+        }
+        return sets.get(key);
+    }
+
+    function createMulti() {
+        const commands = [];
+
+        const chain = {
+            hmset(key, obj) {
+                commands.push(() => redis.hmset(key, obj));
+                return chain;
+            },
+            set(key, value) {
+                commands.push(() => redis.set(key, value));
+                return chain;
+            },
+            expire(key, ttl) {
+                commands.push(() => ttl);
+                return chain;
+            },
+            hdel(key, ...fields) {
+                commands.push(() => redis.hdel(key, ...fields));
+                return chain;
+            },
+            hincrby(key, field, increment) {
+                commands.push(() => redis.hincrby(key, field, increment));
+                return chain;
+            },
+            sadd(key, member) {
+                commands.push(() => redis.sadd(key, member));
+                return chain;
+            },
+            srem(key, member) {
+                commands.push(() => redis.srem(key, member));
+                return chain;
+            },
+            async exec() {
+                const results = [];
+                for (const cmd of commands) {
+                    try {
+                        const result = await cmd();
+                        results.push([null, result]);
+                    } catch (err) {
+                        results.push([err, null]);
+                    }
+                }
+                return results;
+            }
+        };
+
+        return chain;
+    }
+
+    const redis = {
+        async hmset(key, obj) {
+            const hash = getHash(key);
+            for (const [field, value] of Object.entries(obj)) {
+                hash.set(field, Buffer.isBuffer(value) ? value : Buffer.from(String(value)));
+            }
+            return 'OK';
+        },
+
+        async hmgetBuffer(key, fields) {
+            const hash = getHash(key);
+            return fields.map(f => hash.get(f) || null);
+        },
+
+        async hdel(key, ...fields) {
+            const hash = getHash(key);
+            let count = 0;
+            for (const f of fields) {
+                if (hash.delete(f)) count++;
+            }
+            return count;
+        },
+
+        async hexists(key, field) {
+            const hash = getHash(key);
+            return hash.has(field) ? 1 : 0;
+        },
+
+        async hget(key, field) {
+            const hash = getHash(key);
+            const val = hash.get(field);
+            return val ? val.toString() : null;
+        },
+
+        async hincrby(key, field, increment) {
+            const hash = getHash(key);
+            const current = hash.get(field) ? parseInt(hash.get(field).toString(), 10) : 0;
+            const newVal = current + increment;
+            hash.set(field, Buffer.from(String(newVal)));
+            return newVal;
+        },
+
+        async set(key, value) {
+            keys.set(key, Buffer.isBuffer(value) ? value : Buffer.from(String(value)));
+            return 'OK';
+        },
+
+        async get(key) {
+            const val = keys.get(key);
+            return val ? val.toString() : null;
+        },
+
+        async getBuffer(key) {
+            return keys.get(key) || null;
+        },
+
+        async del(key) {
+            return keys.delete(key) ? 1 : 0;
+        },
+
+        async exists(key) {
+            return keys.has(key) ? 1 : 0;
+        },
+
+        async sadd(key, member) {
+            const s = getSet(key);
+            const had = s.has(member);
+            s.add(member);
+            return had ? 0 : 1;
+        },
+
+        async srem(key, member) {
+            const s = getSet(key);
+            return s.delete(member) ? 1 : 0;
+        },
+
+        async smembers(key) {
+            const s = sets.get(key);
+            return s ? Array.from(s) : [];
+        },
+
+        multi() {
+            return createMulti();
+        }
+    };
+
+    return redis;
+}
+
+module.exports = { createMockRedis };

package/test/settings.test.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const { describe, it, beforeEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { Settings } = require('../lib/settings');
+const { createMockRedis } = require('./helpers/mock-redis');
+
+describe('Settings', () => {
+    let redis;
+    let settings;
+
+    beforeEach(() => {
+        redis = createMockRedis();
+        settings = Settings.create({ redis, namespace: 'test' });
+    });
+
+    describe('create', () => {
+        it('should return a Settings instance', () => {
+            assert.ok(settings instanceof Settings);
+        });
+    });
+
+    describe('getKey', () => {
+        it('should prefix with namespace', () => {
+            assert.equal(settings.getKey('settings'), 'test:certs:settings');
+        });
+
+        it('should work without namespace', () => {
+            const s = Settings.create({ redis });
+            assert.equal(s.getKey('settings'), 'certs:settings');
+        });
+    });
+
+    describe('set and get', () => {
+        it('should roundtrip a single key-value pair', async () => {
+            await settings.set('mykey', 'myvalue');
+            const result = await settings.get('mykey');
+            assert.equal(result, 'myvalue');
+        });
+
+        it('should roundtrip an object of key-value pairs', async () => {
+            await settings.set({ key1: 'val1', key2: 'val2' });
+            const result = await settings.get(['key1', 'key2']);
+            assert.equal(result.key1, 'val1');
+            assert.equal(result.key2, 'val2');
+        });
+
+        it('should handle object values', async () => {
+            const obj = { nested: { deep: true }, arr: [1, 2, 3] };
+            await settings.set('complex', obj);
+            const result = await settings.get('complex');
+            assert.deepEqual(result, obj);
+        });
+
+        it('should handle numeric values', async () => {
+            await settings.set('num', 42);
+            const result = await settings.get('num');
+            assert.equal(result, 42);
+        });
+
+        it('should handle null values', async () => {
+            await settings.set('empty', null);
+            const result = await settings.get('empty');
+            assert.equal(result, null);
+        });
+
+        it('should return undefined for non-existent single key', async () => {
+            const result = await settings.get('nonexistent');
+            assert.equal(result, undefined);
+        });
+
+        it('should return object with undefined values for non-existent multiple keys', async () => {
+            const result = await settings.get(['a', 'b']);
+            assert.equal(result.a, undefined);
+            assert.equal(result.b, undefined);
+        });
+
+        it('should return false for invalid set arguments', async () => {
+            const result = await settings.set();
+            assert.equal(result, false);
+        });
+    });
+
+    describe('delete', () => {
+        it('should delete existing keys', async () => {
+            await settings.set('todelete', 'value');
+            await settings.delete('todelete');
+            const result = await settings.get('todelete');
+            assert.equal(result, undefined);
+        });
+
+        it('should handle deleting non-existent keys', async () => {
+            const result = await settings.delete('nonexistent');
+            assert.equal(result, 0);
+        });
+    });
+
+    describe('has', () => {
+        it('should return truthy for existing key', async () => {
+            await settings.set('exists', 'yes');
+            const result = await settings.has('exists');
+            assert.ok(result);
+        });
+
+        it('should return falsy for non-existent key', async () => {
+            const result = await settings.has('nope');
+            assert.ok(!result);
+        });
+    });
+
+    describe('getSet', () => {
+        it('should add hmset command to pipeline', async () => {
+            const multi = redis.multi();
+            const result = settings.getSet(multi, { pipekey: 'pipeval' });
+            assert.notEqual(result, false);
+
+            // Execute and verify
+            await result.exec();
+            const val = await settings.get('pipekey');
+            assert.equal(val, 'pipeval');
+        });
+
+        it('should accept key-value as separate args', async () => {
+            const multi = redis.multi();
+            const result = settings.getSet(multi, 'singlekey', 'singleval');
+            assert.notEqual(result, false);
+
+            await result.exec();
+            const val = await settings.get('singlekey');
+            assert.equal(val, 'singleval');
+        });
+
+        it('should return false for invalid arguments', () => {
+            const multi = redis.multi();
+            assert.equal(settings.getSet(multi), false);
+            assert.equal(settings.getSet(multi, 1, 2, 3), false);
+        });
+    });
+});

package/test/tools.test.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const { describe, it, before } = require('node:test');
+const assert = require('node:assert/strict');
+const { normalizeDomain, generateKey, parseCertificate, validationErrors } = require('../lib/tools');
+
+// Static self-signed cert with CN=test.example.com, SAN=DNS:test.example.com,DNS:www.example.com
+const TEST_CERT = `-----BEGIN CERTIFICATE-----
+MIIDRjCCAi6gAwIBAgIUDGr1Y4+8MTxJRO3g9lGDp+hgUeEwDQYJKoZIhvcNAQEL
+BQAwGzEZMBcGA1UEAwwQdGVzdC5leGFtcGxlLmNvbTAeFw0yNjAzMjMxMjU5NTda
+Fw0yNzAzMjMxMjU5NTdaMBsxGTAXBgNVBAMMEHRlc3QuZXhhbXBsZS5jb20wggEi
+MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC0E0ZqEGKPJLOsgK07VSb/3+CI
+8ID6D90bd0u5BFzoZ6TvVy3c8SKQxlmLtxPCRSBkSUfzGeJgc6iSYTe5sUkvXtdP
+J6qSy/cg51hSdK1oyso0fv5elqFXNnffJ7rOuONLHEm4hv5PTaDqKmsh27iWmI/e
+4sr2+z66+19bCdRCDDMqNbyveMFLvb8XsgV020d5HI9cPierTsVH+DRwk0ODJVfl
+SzcKgPoIcAZBRr7GSZ7mwpHzYGQMf8W3sa148BjvojCb4hJf1q8CH7ZQiVahlokZ
+hw0R/zs/0kD5CLdaOoevT9ibiZHeI2HY1YaOg5lZKbyUnNWC/roE0IvpAcd5AgMB
+AAGjgYEwfzAdBgNVHQ4EFgQUFWPYVG/9myi+0z60aGkaV0iy/WMwHwYDVR0jBBgw
+FoAUFWPYVG/9myi+0z60aGkaV0iy/WMwDwYDVR0TAQH/BAUwAwEB/zAsBgNVHREE
+JTAjghB0ZXN0LmV4YW1wbGUuY29tgg93d3cuZXhhbXBsZS5jb20wDQYJKoZIhvcN
+AQELBQADggEBAKs1ACCedoZo1DEgtevPNk8PPAtLUHGXst+HVf8w+TFDgo4ICPUJ
+8/8QXfcd5obzLSb+aBTGvSvu0WKce2aRkHY7OM9GSzyHwwXDsHoOrAnpjgyS6sbZ
+RpiOMWSxnfSL+a+6drc9bc4dylCsDOYr2tAwnyaEPNs++Y1jk0gZYuHr9xmjVT8W
+wQyi66bOjBdalHReVyOrQKHQWA+oWng24nHBe33IbV6BU21OyRnmwbBPM2KDcAts
+1Lj2DVby5K8jFAAHOt767nofpxeb8wi504UkBe8DT10x+uxuH1GUh1Qj2Xp1aMbb
+oCw05NWfWop5EANNovcHvYyBe9CLmEhKhu0=
+-----END CERTIFICATE-----`;
+
+describe('normalizeDomain', () => {
+    it('should lowercase and trim a domain', () => {
+        assert.equal(normalizeDomain('  Example.COM  '), 'example.com');
+    });
+
+    it('should return empty string for null/undefined', () => {
+        assert.equal(normalizeDomain(null), '');
+        assert.equal(normalizeDomain(undefined), '');
+        assert.equal(normalizeDomain(''), '');
+    });
+
+    it('should convert punycode to unicode', () => {
+        const result = normalizeDomain('xn--nxasmq6b');
+        assert.notEqual(result, 'xn--nxasmq6b');
+        assert.ok(result.length > 0);
+    });
+
+    it('should handle non-punycode domains unchanged', () => {
+        assert.equal(normalizeDomain('example.com'), 'example.com');
+    });
+
+    it('should not throw on invalid punycode', () => {
+        const result = normalizeDomain('xn--');
+        assert.equal(typeof result, 'string');
+    });
+
+    it('should handle already lowercase domains', () => {
+        assert.equal(normalizeDomain('test.example.com'), 'test.example.com');
+    });
+});
+
+describe('generateKey', () => {
+    it('should generate a valid PEM private key', async () => {
+        const key = await generateKey(1024);
+        assert.ok(key.startsWith('-----BEGIN RSA PRIVATE KEY-----'));
+        assert.ok(key.includes('-----END RSA PRIVATE KEY-----'));
+    });
+});
+
+describe('parseCertificate', () => {
+    let parsed;
+
+    before(() => {
+        parsed = parseCertificate(TEST_CERT);
+    });
+
+    it('should parse serial number', () => {
+        assert.ok(parsed.serialNumber);
+        assert.equal(typeof parsed.serialNumber, 'string');
+    });
+
+    it('should parse fingerprint', () => {
+        assert.ok(parsed.fingerprint);
+        assert.ok(parsed.fingerprint.includes(':'));
+    });
+
+    it('should parse alt names', () => {
+        assert.ok(Array.isArray(parsed.altNames));
+        assert.ok(parsed.altNames.includes('test.example.com'));
+        assert.ok(parsed.altNames.includes('www.example.com'));
+    });
+
+    it('should parse validity dates', () => {
+        assert.ok(parsed.validFrom instanceof Date);
+        assert.ok(parsed.validTo instanceof Date);
+        assert.ok(parsed.validTo > parsed.validFrom);
+    });
+
+    it('should deduplicate domain names', () => {
+        const unique = new Set(parsed.altNames);
+        assert.equal(parsed.altNames.length, unique.size);
+    });
+
+    it('should throw on invalid certificate', () => {
+        assert.throws(() => parseCertificate('not a cert'), { name: 'Error' });
+    });
+});
+
+describe('validationErrors', () => {
+    it('should extract errors from validation result', () => {
+        const result = validationErrors({
+            error: {
+                details: [{ path: 'email', message: 'Email is required' }]
+            }
+        });
+        assert.deepEqual(result, { email: 'Email is required' });
+    });
+
+    it('should handle multiple errors on different paths', () => {
+        const result = validationErrors({
+            error: {
+                details: [
+                    { path: 'email', message: 'Email is required' },
+                    { path: 'name', message: 'Name is required' }
+                ]
+            }
+        });
+        assert.deepEqual(result, {
+            email: 'Email is required',
+            name: 'Name is required'
+        });
+    });
+
+    it('should keep only first error per path', () => {
+        const result = validationErrors({
+            error: {
+                details: [
+                    { path: 'email', message: 'First error' },
+                    { path: 'email', message: 'Second error' }
+                ]
+            }
+        });
+        assert.deepEqual(result, { email: 'First error' });
+    });
+
+    it('should return empty object when no errors', () => {
+        assert.deepEqual(validationErrors({}), {});
+        assert.deepEqual(validationErrors({ error: {} }), {});
+        assert.deepEqual(validationErrors({ error: { details: [] } }), {});
+    });
+});