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.
npm install @postalsys/certs
Requirements: Node.js 15+ (for CAA record validation), Redis
constRedis=require('ioredis');constexpress=require('express');const{ Certs }=require('@postalsys/certs');constredis=newRedis();constapp=express();constcerts=newCerts({
redis,namespace: 'myapp',acme: {// Use 'production' and the production directory URL for real certificatesenvironment: 'production',directoryUrl: 'https://acme-v02.api.letsencrypt.org/directory',email: 'admin@example.com'},// Optional: encrypt private keys before storing in RedisencryptFn: async(value)=>{// your encryption logicreturnencryptedValue;},decryptFn: async(value)=>{// your decryption logicreturndecryptedValue;}});// Retrieve or acquire a certificateconstcertData=awaitcerts.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 handlerapp.get('/.well-known/acme-challenge/:token',(req,res)=>{consttoken=req.params.token;constdomain=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});});});| 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) |
Static factory method. Returns a new Certs instance.
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.
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.
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.
Returns a sorted array of all domain names that have certificate records.
Removes all stored certificate data for the domain.
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.
ISC