@push.rocks/smartacme 8.0.0 → 9.0.1

package/readme.md

@@ -1,361 +1,339 @@
 # @push.rocks/smartacme
 
-A TypeScript-based ACME client with an easy yet powerful interface for LetsEncrypt certificate management.
+A TypeScript-based ACME client for Let's Encrypt certificate management with a focus on simplicity and power. 🔒
 
-## Install
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-Using pnpm as the package manager:
+## Install
 
 ```bash
 pnpm add @push.rocks/smartacme
 ```
 
-Ensure your project is set up to use TypeScript and ECMAScript Modules (ESM).
-## Running Tests
+Ensure your project uses TypeScript and ECMAScript Modules (ESM).
 
-Tests are written using `@push.rocks/tapbundle` and can be run with:
+## Usage
 
-```bash
-pnpm test
+`@push.rocks/smartacme` automates the full ACME certificate lifecycle — obtaining, renewing, and storing SSL/TLS certificates from Let's Encrypt. It features a built-in RFC 8555-compliant ACME protocol implementation, pluggable challenge handlers (DNS-01, HTTP-01), pluggable certificate storage backends (MongoDB, in-memory, or your own), and structured error handling with smart retry logic.
+
+### 🚀 Quick Start
+
+```typescript
+import { SmartAcme, certmanagers, handlers } from '@push.rocks/smartacme';
+import * as cloudflare from '@apiclient.xyz/cloudflare';
+
+// 1. Set up a certificate manager (MongoDB or in-memory)
+const certManager = new certmanagers.MongoCertManager({
+  mongoDbUrl: 'mongodb://localhost:27017',
+  mongoDbName: 'myapp',
+  mongoDbPass: 'secret',
+});
+
+// 2. Set up challenge handlers
+const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_API_TOKEN');
+const dnsHandler = new handlers.Dns01Handler(cfAccount);
+
+// 3. Create and start SmartAcme
+const smartAcme = new SmartAcme({
+  accountEmail: 'admin@example.com',
+  certManager,
+  environment: 'production', // or 'integration' for staging
+  challengeHandlers: [dnsHandler],
+});
+
+await smartAcme.start();
+
+// 4. Get a certificate
+const cert = await smartAcme.getCertificateForDomain('example.com');
+console.log(cert.publicKey);  // PEM certificate chain
+console.log(cert.privateKey); // PEM private key
+
+// 5. Clean up
+await smartAcme.stop();
 ```
 
-To run a specific test file:
+### ⚙️ SmartAcme Options
 
-```bash
-tsx test/<test-file>.ts
+```typescript
+interface ISmartAcmeOptions {
+  accountEmail: string;                    // ACME account email
+  accountPrivateKey?: string;              // Optional account key (auto-generated if omitted)
+  certManager: ICertManager;               // Certificate storage backend
+  environment: 'production' | 'integration'; // Let's Encrypt environment
+  challengeHandlers: IChallengeHandler[];  // At least one handler required
+  challengePriority?: string[];            // e.g. ['dns-01', 'http-01']
+  retryOptions?: {                         // Optional retry/backoff config
+    retries?: number;                      // Default: 10
+    factor?: number;                       // Default: 4
+    minTimeoutMs?: number;                 // Default: 1000
+    maxTimeoutMs?: number;                 // Default: 60000
+  };
+}
 ```
 
-## Usage
+### 📜 Getting Certificates
+
+```typescript
+// Standard certificate for a single domain
+const cert = await smartAcme.getCertificateForDomain('example.com');
 
-This guide will walk you through using `@push.rocks/smartacme` to set up and manage ACME (Automated Certificate Management Environment) certificates with a focus on the Let's Encrypt service, which provides free SSL certificates. The library provides an easy yet powerful TypeScript interface to automate the process of obtaining, renewing, and installing your SSL certificates.
+// Include wildcard coverage (requires DNS-01 handler)
+// Issues a single cert covering example.com AND *.example.com
+const certWithWildcard = await smartAcme.getCertificateForDomain('example.com', {
+  includeWildcard: true,
+});
 
-### Table of Contents
+// Request wildcard only
+const wildcardCert = await smartAcme.getCertificateForDomain('*.example.com');
+```
 
-1. [Setting Up Your Project](#setting-up-your-project)
-2. [Creating a SmartAcme Instance](#creating-a-smartacme-instance)
-3. [Initializing SmartAcme](#initializing-smartacme)
-4. [Obtaining a Certificate for a Domain](#obtaining-a-certificate-for-a-domain)
-5. [Automating DNS Challenges](#automating-dns-challenges)
-6. [Managing Certificates](#managing-certificates)
-7. [Environmental Considerations](#environmental-considerations)
-8. [Complete Example](#complete-example)
+Certificates are automatically cached and reused when still valid. Renewal happens automatically when a certificate is within 10 days of expiration.
 
-### Setting Up Your Project
+### 📦 Certificate Object
 
-Ensure your project includes the necessary TypeScript configuration and dependencies. You'll need to have TypeScript installed and configured for ECMAScript Modules. If you are new to TypeScript, review its [documentation](https://www.typescriptlang.org/docs/) to get started.
+The returned `SmartacmeCert` (also exported as `Cert`) object has these properties:
 
-### Creating a SmartAcme Instance
+| Property     | Type     | Description                          |
+|-------------|----------|--------------------------------------|
+| `id`        | `string` | Unique certificate identifier        |
+| `domainName`| `string` | Domain the cert is issued for        |
+| `publicKey` | `string` | PEM-encoded certificate chain        |
+| `privateKey`| `string` | PEM-encoded private key              |
+| `csr`       | `string` | Certificate Signing Request          |
+| `created`   | `number` | Timestamp of creation                |
+| `validUntil`| `number` | Timestamp of expiration              |
 
-Start by importing the `SmartAcme` class and any built-in handlers you plan to use. For example, to use DNS-01 via Cloudflare:
+Useful methods:
 
 ```typescript
-import { SmartAcme, MongoCertManager } from '@push.rocks/smartacme';
-import * as cloudflare from '@apiclient.xyz/cloudflare';
-import { Dns01Handler } from '@push.rocks/smartacme/ts/handlers/Dns01Handler.js';
+cert.isStillValid();    // true if not expired
+cert.shouldBeRenewed(); // true if expires within 10 days
+```
 
-// Create a Cloudflare account client with your API token
-const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_TOKEN');
+## Certificate Managers
 
-// Initialize a certificate manager (e.g., MongoDB)
-const certManager = new MongoCertManager({
-  mongoDbUrl: 'mongodb://yourmongoURL',
-  mongoDbName: 'yourDbName',
-  mongoDbPass: 'yourDbPassword',
-});
+SmartAcme uses the `ICertManager` interface for pluggable certificate storage.
 
-// Instantiate SmartAcme with the certManager and challenge handlers
-const smartAcmeInstance = new SmartAcme({
-  accountEmail: 'youremail@example.com',
-  certManager,
-  environment: 'integration', // 'production' to request real certificates
-  retryOptions: {},           // optional retry/backoff settings
-  challengeHandlers: [        // pluggable ACME challenge handlers
-    new Dns01Handler(cfAccount),
-    // add more handlers as needed (e.g., Http01Webroot, Http01MemoryHandler)
-  ],
-  challengePriority: ['dns-01'], // optional challenge ordering
+### 🗄️ MongoCertManager
+
+Persistent storage backed by MongoDB using `@push.rocks/smartdata`:
+
+```typescript
+import { certmanagers } from '@push.rocks/smartacme';
+
+const certManager = new certmanagers.MongoCertManager({
+  mongoDbUrl: 'mongodb://localhost:27017',
+  mongoDbName: 'myapp',
+  mongoDbPass: 'secret',
 });
 ```
 
-### Initializing SmartAcme
+### 🧪 MemoryCertManager
 
-Before proceeding to request certificates, start your SmartAcme instance:
+In-memory storage, ideal for testing or ephemeral workloads:
 
 ```typescript
-await smartAcmeInstance.start();
+import { certmanagers } from '@push.rocks/smartacme';
+
+const certManager = new certmanagers.MemoryCertManager();
 ```
 
-### Obtaining a Certificate for a Domain
+### 🔧 Custom Certificate Manager
 
-To obtain a certificate for a specific domain, use the `getCertificateForDomain` method. This function ensures that if a valid certificate is already present, it will be reused; otherwise, a new certificate is obtained:
+Implement the `ICertManager` interface for your own storage backend:
 
 ```typescript
-const myDomain = 'example.com';
-const myCert = await smartAcmeInstance.getCertificateForDomain(myDomain);
-console.log('Certificate:', myCert);
+import type { ICertManager, Cert } from '@push.rocks/smartacme';
+
+class RedisCertManager implements ICertManager {
+  async init(): Promise<void> { /* connect */ }
+  async retrieveCertificate(domainName: string): Promise<Cert | null> { /* lookup */ }
+  async storeCertificate(cert: Cert): Promise<void> { /* save */ }
+  async deleteCertificate(domainName: string): Promise<void> { /* remove */ }
+  async close(): Promise<void> { /* disconnect */ }
+  async wipe(): Promise<void> { /* clear all */ }
+}
 ```
 
-### Automating DNS Challenges
+## Challenge Handlers
+
+SmartAcme ships with three built-in ACME challenge handlers. All implement `IChallengeHandler<T>`.
 
-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.
+### 🌐 Dns01Handler
 
-### Managing Certificates
+Uses Cloudflare (or any `IConvenientDnsProvider`) to set and remove DNS TXT records for `dns-01` challenges:
 
-The library automatically handles fetching, renewing, and storing your certificates in a MongoDB database specified via a certificate manager. Ensure your MongoDB instance is accessible and properly configured for use with SmartAcme.
+```typescript
+import { handlers } from '@push.rocks/smartacme';
+import * as cloudflare from '@apiclient.xyz/cloudflare';
+
+const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_TOKEN');
+const dnsHandler = new handlers.Dns01Handler(cfAccount);
+```
+
+DNS-01 is **required** for wildcard certificates and works regardless of server accessibility.
+
+### 📁 Http01Webroot
+
+Writes challenge response files to a filesystem webroot for `http-01` validation:
 
 ```typescript
-import { MongoCertManager } from '@push.rocks/smartacme';
+import { handlers } from '@push.rocks/smartacme';
 
-const certManager = new MongoCertManager({
-  mongoDbUrl: 'mongodb://yourmongoURL',
-  mongoDbName: 'yourDbName',
-  mongoDbPass: 'yourDbPassword',
+const httpHandler = new handlers.Http01Webroot({
+  webroot: '/var/www/html',
 });
 ```
 
-SmartAcme uses the `ICertManager` interface for certificate storage. Two built-in implementations are available:
+The handler writes to `<webroot>/.well-known/acme-challenge/<token>` and cleans up after validation.
+
+### 🧠 Http01MemoryHandler
+
+In-memory HTTP-01 handler — stores challenge tokens in memory and serves them via `handleRequest()`:
 
-- **MemoryCertManager**
-  - In-memory storage, suitable for testing or ephemeral use.
-  - Import example:
-    ```typescript
-    import { MemoryCertManager } from '@push.rocks/smartacme';
-    const certManager = new MemoryCertManager();
-    ```
+```typescript
+import { handlers } from '@push.rocks/smartacme';
+
+const memHandler = new handlers.Http01MemoryHandler();
 
-- **MongoCertManager**
-  - Persistent storage in MongoDB (collection: `SmartacmeCert`).
-  - Import example:
-    ```typescript
-    import { MongoCertManager } from '@push.rocks/smartacme';
-    const certManager = new MongoCertManager({
-      mongoDbUrl: 'mongodb://yourmongoURL',
-      mongoDbName: 'yourDbName',
-      mongoDbPass: 'yourDbPassword',
-    });
-    ```
+// Integrate with any HTTP server (Express, Koa, raw http, etc.)
+app.use((req, res, next) => memHandler.handleRequest(req, res, next));
+```
 
-#### Custom Certificate Managers
+Perfect for serverless or container environments where filesystem access is limited.
 
-To implement a custom certificate manager, implement the `ICertManager` interface and pass it to `SmartAcme`:
+### 🔧 Custom Challenge Handler
+
+Implement `IChallengeHandler<T>` for custom challenge types:
 
 ```typescript
-import type { ICertManager, Cert as SmartacmeCert } from '@push.rocks/smartacme';
-import { SmartAcme } from '@push.rocks/smartacme';
-
-class MyCustomCertManager implements ICertManager {
-  async init(): Promise<void> { /* setup storage */ }
-  async get(domainName: string): Promise<SmartacmeCert | null> { /* lookup cert */ }
-  async put(cert: SmartacmeCert): Promise<SmartacmeCert> { /* store cert */ }
-  async delete(domainName: string): Promise<void> { /* remove cert */ }
-  async close?(): Promise<void> { /* optional cleanup */ }
+import type { handlers } from '@push.rocks/smartacme';
+
+interface MyChallenge {
+  type: string;
+  token: string;
+  keyAuthorization: string;
 }
 
-// Use your custom manager:
-const customManager = new MyCustomCertManager();
-const smartAcme = new SmartAcme({
-  accountEmail: 'youremail@example.com',
-  certManager: customManager,
-  environment: 'integration',
-  challengeHandlers: [], // add your handlers
-});
+class MyHandler implements handlers.IChallengeHandler<MyChallenge> {
+  getSupportedTypes(): string[] { return ['http-01']; }
+  async prepare(ch: MyChallenge): Promise<void> { /* set up challenge response */ }
+  async cleanup(ch: MyChallenge): Promise<void> { /* tear down */ }
+  async checkWetherDomainIsSupported(domain: string): Promise<boolean> { return true; }
+}
 ```
 
-### Environmental Considerations
+## Error Handling
 
-When creating an instance of `SmartAcme`, you can specify an `environment` option. This is particularly useful for testing, as you can use the `integration` environment to avoid hitting rate limits and for testing your setup without issuing real certificates. Switch to `production` when you are ready to obtain actual certificates.
+SmartAcme provides structured ACME error handling via the `AcmeError` class, which carries full RFC 8555 error information:
 
-### Complete Example
+```typescript
+import { AcmeError } from '@push.rocks/smartacme/ts/acme/acme.classes.error.js';
+
+try {
+  const cert = await smartAcme.getCertificateForDomain('example.com');
+} catch (err) {
+  if (err instanceof AcmeError) {
+    console.log(err.status);        // HTTP status code (e.g. 429)
+    console.log(err.type);          // ACME error URN (e.g. 'urn:ietf:params:acme:error:rateLimited')
+    console.log(err.detail);        // Human-readable message
+    console.log(err.subproblems);   // Per-identifier sub-errors (RFC 8555 §6.7.1)
+    console.log(err.retryAfter);    // Retry-After value in seconds
+    console.log(err.isRateLimited); // true for 429 or rateLimited type
+    console.log(err.isRetryable);   // true for 429, 503, 5xx, badNonce; false for 403/404/409
+  }
+}
+```
 
-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:
+The built-in retry logic is **error-aware**: non-retryable errors (403, 404, 409) are thrown immediately without wasting retry attempts, and rate-limited responses respect the server's `Retry-After` header instead of using blind exponential backoff.
 
-```typescript
-import { SmartAcme, MongoCertManager } from '@push.rocks/smartacme';
-import * as cloudflare from '@apiclient.xyz/cloudflare';
-import { Qenv } from '@push.rocks/qenv';
-import { Dns01Handler } from '@push.rocks/smartacme/ts/handlers/Dns01Handler.js';
-
-const qenv = new Qenv('./', './.nogit/');
-const cloudflareAccount = new cloudflare.CloudflareAccount(qenv.getEnvVarOnDemand('CF_TOKEN'));
-
-async function main() {
-  // Initialize MongoDB certificate manager
-  const certManager = new MongoCertManager({
-    mongoDbUrl: qenv.getEnvVarRequired('MONGODB_URL'),
-    mongoDbName: qenv.getEnvVarRequired('MONGODB_DATABASE'),
-    mongoDbPass: qenv.getEnvVarRequired('MONGODB_PASSWORD'),
-  });
+## Domain Matching
 
-  const smartAcmeInstance = new SmartAcme({
-    accountEmail: 'youremail@example.com',
-    certManager,
-    environment: 'integration',
-    challengeHandlers: [new Dns01Handler(cloudflareAccount)],
-  });
+SmartAcme automatically maps subdomains to their base domain for certificate lookups:
 
-  await smartAcmeInstance.start();
+```
+subdomain.example.com → certificate for example.com  ✅
+*.example.com         → certificate for example.com  ✅
+a.b.example.com       → not supported (4+ levels)    ❌
+```
 
-  const myDomain = 'example.com';
-  // Get certificate for domain (no wildcard)
-  const myCert = await smartAcmeInstance.getCertificateForDomain(myDomain);
-  console.log('Certificate:', myCert);
-  
-  // Get certificate with wildcard (requires DNS-01 handler)
-  const certWithWildcard = await smartAcmeInstance.getCertificateForDomain(myDomain, { includeWildcard: true });
-  console.log('Certificate with wildcard:', certWithWildcard);
+## Environment
 
-  await smartAcmeInstance.stop();
-}
+| Environment     | Description |
+|----------------|-------------|
+| `production`   | Let's Encrypt production servers. Certificates are browser-trusted. [Rate limits](https://letsencrypt.org/docs/rate-limits/) apply. |
+| `integration`  | Let's Encrypt staging servers. No rate limits, but certificates are **not** browser-trusted. Use for testing. |
 
-main().catch(console.error);
-```
- 
- ## Built-in Challenge Handlers
- 
- This module includes three 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);
-     ```
- 
- - **Http01Webroot**
-   - Writes ACME HTTP-01 challenge files under a file-system webroot (`/.well-known/acme-challenge/`), and removes them on cleanup.
-   - Import path:
-     ```typescript
-     import { Http01Webroot } from '@push.rocks/smartacme/ts/handlers/Http01Handler.js';
-     ```
-   - Example:
-     ```typescript
-     const httpHandler = new Http01Webroot({ webroot: '/var/www/html' });
-     ```
- 
- - **Http01MemoryHandler**
-   - In-memory HTTP-01 challenge handler that stores and serves ACME tokens without disk I/O.
-   - Import path:
-     ```typescript
-     import { Http01MemoryHandler } from '@push.rocks/smartacme/ts/handlers/Http01MemoryHandler.js';
-     ```
-   - Example (Express integration):
-     ```typescript
-     import { Http01MemoryHandler } from '@push.rocks/smartacme/ts/handlers/Http01MemoryHandler.js';
-     const memoryHandler = new Http01MemoryHandler();
-     app.use((req, res, next) => memoryHandler.handleRequest(req, res, next));
-     ```
-  
- All 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 the Cloudflare library is used to handle DNS challenges through the built-in `Dns01Handler` plugin.
-
-## Additional Details
-
-### Certificate Object
-
-The certificate object obtained from the `getCertificateForDomain` method has the following properties:
-
-- `id`: Unique identifier for the certificate.
-- `domainName`: The domain name for which the certificate is issued.
-- `created`: Timestamp of when the certificate was created.
-- `privateKey`: The private key associated with the certificate.
-- `publicKey`: The public key or certificate itself.
-- `csr`: Certificate Signing Request (CSR) used to obtain the certificate.
-- `validUntil`: Timestamp indicating the expiration date of the certificate.
-
-### Methods Summary
-
-- **start()**: Initializes the SmartAcme instance, sets up the ACME client, and registers the account with Let's Encrypt.
-- **stop()**: Closes the MongoDB connection and performs any necessary cleanup.
-- **getCertificateForDomain(domainArg: string, options?: { includeWildcard?: boolean })**: Retrieves or obtains a certificate for the specified domain name. If a valid certificate exists in the database, it is returned. Otherwise, a new certificate is requested and stored. 
-  - By default, only a certificate for the exact domain is requested
-  - Set `includeWildcard: true` to also request a wildcard certificate (requires DNS-01 handler)
-  - When requesting a wildcard directly (e.g., `*.example.com`), only the wildcard certificate is requested
-
-### Handling Domain Matching
-
-The `SmartacmeCertMatcher` class is responsible for matching certificates with the broadest scope for wildcard certificates. The `getCertificateDomainNameByDomainName` method ensures that domains at various levels are correctly matched.
+## Complete Example with HTTP-01
 
 ```typescript
-import { SmartacmeCertMatcher } from '@push.rocks/smartacme';
+import { SmartAcme, certmanagers, handlers } from '@push.rocks/smartacme';
+import * as http from 'http';
 
-const certMatcher = new SmartacmeCertMatcher();
-const certDomainName = certMatcher.getCertificateDomainNameByDomainName('subdomain.example.com');
-console.log('Certificate Domain Name:', certDomainName); // Output: example.com
-```
+// In-memory handler for HTTP-01 challenges
+const memHandler = new handlers.Http01MemoryHandler();
 
-### Testing
+// Create HTTP server that serves ACME challenges
+const server = http.createServer((req, res) => {
+  memHandler.handleRequest(req, res, () => {
+    res.statusCode = 200;
+    res.end('OK');
+  });
+});
+server.listen(80);
 
-Sample tests are provided in the `test` directory. They demonstrate core functionality using the `MemoryCertManager` and built-in challenge handlers. To run all tests, use:
+// Set up SmartAcme with in-memory storage and HTTP-01
+const smartAcme = new SmartAcme({
+  accountEmail: 'admin@example.com',
+  certManager: new certmanagers.MemoryCertManager(),
+  environment: 'production',
+  challengeHandlers: [memHandler],
+  challengePriority: ['http-01'],
+});
 
-```bash
-pnpm test
+await smartAcme.start();
+
+const cert = await smartAcme.getCertificateForDomain('example.com');
+// Use cert.publicKey and cert.privateKey with your HTTPS server
+
+await smartAcme.stop();
+server.close();
 ```
 
+## Architecture
 
-This comprehensive guide ensures you can set up, manage, and test ACME certificates efficiently and effectively using `@push.rocks/smartacme`.
+Under the hood, SmartAcme uses a fully custom RFC 8555-compliant ACME protocol implementation (no external ACME libraries). Key internal modules:
 
----
+| Module | Purpose |
+|--------|---------|
+| `AcmeClient` | Top-level ACME facade — orders, authorizations, finalization |
+| `AcmeCrypto` | RSA key generation, JWK/JWS (RFC 7515/7638), CSR via `@peculiar/x509` |
+| `AcmeHttpClient` | JWS-signed HTTP transport with nonce management and structured logging |
+| `AcmeError` | Structured error class with type URN, subproblems, Retry-After, retryability |
+| `AcmeOrderManager` | Order lifecycle — create, poll, finalize, download certificate |
+| `AcmeChallengeManager` | Key authorization computation and challenge completion |
+
+All cryptographic operations use `node:crypto`. The only external crypto dependency is `@peculiar/x509` for CSR generation.
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license.md](license.md) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

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