@push.rocks/smartacme 6.0.1 → 6.1.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartacme',
-    version: '6.0.1',
+    version: '6.1.0',
     description: 'A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx1QkFBdUI7SUFDN0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLDZHQUE2RztDQUMzSCxDQUFBIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartacme",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "private": false,
   "description": "A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.",
   "main": "dist_ts/index.js",

package/readme.md

@@ -138,8 +138,76 @@ async function main() {
   await smartAcmeInstance.stop();
 }
 
-main().catch(console.error);
-```
+ main().catch(console.error);
+ ```
+ 
+ ## Built-in Challenge Handlers
+ 
+ This module includes two out-of-the-box ACME challenge handlers:
+ 
+ - **Dns01Handler**
+   - Uses a Cloudflare account (from `@apiclient.xyz/cloudflare`) and Smartdns client to set and remove DNS TXT records, then wait for propagation.
+   - Import path:
+     ```typescript
+     import { Dns01Handler } from '@push.rocks/smartacme/ts/handlers/Dns01Handler.js';
+     ```
+   - Example:
+     ```typescript
+     import * as cloudflare from '@apiclient.xyz/cloudflare';
+     const cfAccount = new cloudflare.CloudflareAccount('CF_TOKEN');
+     const dnsHandler = new Dns01Handler(cfAccount);
+     ```
+ 
+ - **Http01Handler**
+   - Writes ACME HTTP-01 challenge files under a file-system webroot (`/.well-known/acme-challenge/`), and removes them on cleanup.
+   - Import path:
+     ```typescript
+     import { Http01Handler } from '@push.rocks/smartacme/ts/handlers/Http01Handler.js';
+     ```
+   - Example:
+     ```typescript
+     const httpHandler = new Http01Handler({ webroot: '/var/www/html' });
+     ```
+ 
+ Both handlers implement the `IChallengeHandler<T>` interface and can be combined in the `challengeHandlers` array.
+ 
+ ## Creating Custom Handlers
+ 
+ To support additional challenge types or custom validation flows, implement the `IChallengeHandler<T>` interface:
+ 
+ ```typescript
+ import type { IChallengeHandler } from '@push.rocks/smartacme/ts/handlers/IChallengeHandler.js';
+ 
+ // Define your custom challenge payload type
+ interface MyChallenge { type: string; /* ... */ }
+ 
+ class MyCustomHandler implements IChallengeHandler<MyChallenge> {
+   getSupportedTypes(): string[] {
+     return ['my-01'];
+   }
+ 
+   // Prepare the challenge (set DNS records, start servers, etc.)
+   async prepare(ch: MyChallenge): Promise<void> {
+     // preparation logic
+   }
+ 
+   // Optional verify step after prepare
+   async verify?(ch: MyChallenge): Promise<void> {
+     // verification logic
+   }
+ 
+   // Cleanup after challenge (remove records, stop servers)
+   async cleanup(ch: MyChallenge): Promise<void> {
+     // cleanup logic
+   }
+ }
+ 
+ // Then register your handler:
+ const customInstance = new SmartAcme({
+   /* other options */, 
+   challengeHandlers: [ new MyCustomHandler() ],
+   challengePriority: ['my-01'],
+ });
 
 In this example, `Qenv` is used to manage environment variables, and `cloudflare` library is used to handle DNS challenges required by Let's Encrypt ACME protocol. The `setChallenge` and `removeChallenge` methods are essential for automating the DNS challenge process, which is a key part of domain validation.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartacme',
-  version: '6.0.1',
+  version: '6.1.0',
   description: 'A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.'
 }