push.rocks/smartacme
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

BREAKING CHANGE(SmartAcme): Refactor challenge handling by removing legacy setChallenge/removeChallenge in favor of pluggable challengeHandlers and update documentation and tests accordingly

Browse Source
This commit is contained in:
Philipp Kunz
2025-04-27 14:28:05 +00:00
parent 48018b8955
commit 58015f0b58
16 changed files with 411 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
readme.md
View File

@ -1,4 +1,3 @@
````markdown
# @push.rocks/smartacme
A TypeScript-based ACME client with an easy yet powerful interface for LetsEncrypt certificate management.
@ -10,7 +9,6 @@ To install `@push.rocks/smartacme`, you can use npm or yarn. Run one of the foll
```bash
npm install @push.rocks/smartacme --save
```
````
or
@ -41,35 +39,40 @@ Ensure your project includes the necessary TypeScript configuration and dependen
### Creating a SmartAcme Instance
Start by importing the `SmartAcme` class from the `@push.rocks/smartacme` package. You'll also need to import or define interfaces for your setup options:
Start by importing the `SmartAcme` class and any built-in handlers you plan to use. For example, to use DNS-01 via Cloudflare:
```typescript
import { SmartAcme } from '@push.rocks/smartacme';
import * as cloudflare from '@apiclient.xyz/cloudflare';
import { Dns01Handler } from '@push.rocks/smartacme/ts/handlers/Dns01Handler.js';
// Create a Cloudflare account client with your API token
const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_TOKEN');
// Instantiate SmartAcme with one or more ACME challenge handlers
const smartAcmeInstance = new SmartAcme({
accountEmail: 'youremail@example.com', // Email used for Let's Encrypt registration and recovery
accountPrivateKey: null, // Private key for the account (optional, if not provided it will be generated)
accountEmail: 'youremail@example.com',
mongoDescriptor: {
mongoDbUrl: 'mongodb://yourmongoURL',
mongoDbName: 'yourDbName',
mongoDbPass: 'yourDbPassword',
},
removeChallenge: async (dnsChallenge) => {
// Implement logic here to remove DNS challenge records
},
setChallenge: async (dnsChallenge) => {
// Implement logic here to create DNS challenge records
},
environment: 'integration', // Use 'production' for actual certificates
environment: 'integration', // 'production' to request real certificates
retryOptions: {}, // optional retry/backoff settings
challengeHandlers: [
new Dns01Handler(cfAccount),
// you can add more handlers, e.g. Http01Handler
],
challengePriority: ['dns-01'], // optional ordering of challenge types
});
```
### Initializing SmartAcme
Before proceeding to request certificates, initialize your SmartAcme instance:
Before proceeding to request certificates, start your SmartAcme instance:
```typescript
await smartAcmeInstance.init();
await smartAcmeInstance.start();
```
### Obtaining a Certificate for a Domain
@ -84,34 +87,7 @@ console.log('Certificate:', myCert);
### Automating DNS Challenges
Part of the ACME protocol involves responding to DNS challenges issued by the certificate authority to prove control over a domain. Implement the `setChallenge` and `removeChallenge` functions in your SmartAcme configuration to automate this process. These functions receive a `dnsChallenge` argument containing details needed to create or remove the necessary DNS records.
```typescript
import * as cloudflare from '@apiclient.xyz/cloudflare';
import { Qenv } from '@push.rocks/qenv';
const testQenv = new Qenv('./', './.nogit/');
const testCloudflare = new cloudflare.CloudflareAccount(testQenv.getEnvVarOnDemand('CF_TOKEN'));
const smartAcmeInstance = new SmartAcme({
accountEmail: 'domains@example.com',
accountPrivateKey: null,
mongoDescriptor: {
mongoDbName: testQenv.getEnvVarRequired('MONGODB_DATABASE'),
mongoDbPass: testQenv.getEnvVarRequired('MONGODB_PASSWORD'),
mongoDbUrl: testQenv.getEnvVarRequired('MONGODB_URL'),
},
removeChallenge: async (dnsChallenge) => {
testCloudflare.convenience.acmeRemoveDnsChallenge(dnsChallenge);
},
setChallenge: async (dnsChallenge) => {
testCloudflare.convenience.acmeSetDnsChallenge(dnsChallenge);
},
environment: 'integration',
});
await smartAcmeInstance.init();
```
SmartAcme uses pluggable ACME challenge handlers (see built-in handlers below) to automate domain validation. You configure handlers via the `challengeHandlers` array when creating the instance, and SmartAcme will invoke each handler’s `prepare`, optional `verify`, and `cleanup` methods during the ACME order flow.
### Managing Certificates
@ -131,7 +107,7 @@ When creating an instance of `SmartAcme`, you can specify an `environment` optio
### Complete Example
Below is a complete example demonstrating how to use `@push.rocks/smartacme` to obtain and manage an ACME certificate with Let's Encrypt:
Below is a complete example demonstrating how to use `@push.rocks/smartacme` to obtain and manage an ACME certificate with Let's Encrypt using a DNS-01 handler:
```typescript
import { SmartAcme } from '@push.rocks/smartacme';
@ -144,22 +120,16 @@ const cloudflareAccount = new cloudflare.CloudflareAccount(qenv.getEnvVarOnDeman
async function main() {
const smartAcmeInstance = new SmartAcme({
accountEmail: 'youremail@example.com',
accountPrivateKey: null,
mongoDescriptor: {
mongoDbUrl: qenv.getEnvVarRequired('MONGODB_URL'),
mongoDbName: qenv.getEnvVarRequired('MONGODB_DATABASE'),
mongoDbPass: qenv.getEnvVarRequired('MONGODB_PASSWORD'),
},
setChallenge: async (dnsChallenge) => {
await cloudflareAccount.convenience.acmeSetDnsChallenge(dnsChallenge);
},
removeChallenge: async (dnsChallenge) => {
await cloudflareAccount.convenience.acmeRemoveDnsChallenge(dnsChallenge);
},
environment: 'integration',
challengeHandlers: [ new Dns01Handler(cloudflareAccount) ],
});
await smartAcmeInstance.init();
await smartAcmeInstance.start();
const myDomain = 'example.com';
const myCert = await smartAcmeInstance.getCertificateForDomain(myDomain);