@postalsys/certs 1.0.12 → 1.0.13

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/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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,6 +1,6 @@
 {
     "name": "@postalsys/certs",
-    "version": "1.0.12",
+    "version": "1.0.13",
     "description": "Manage Let's Encrypt certificates",
     "main": "lib/certs.js",
     "scripts": {
@@ -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.0",
+        "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"
     }
 }