@push.rocks/smartacme 7.3.4 → 9.0.0

package/readme.md

@@ -1,353 +1,299 @@
 # @push.rocks/smartacme
 
-A TypeScript-based ACME client with an easy yet powerful interface for LetsEncrypt certificate management.
+A TypeScript-based ACME client for LetsEncrypt 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 supports pluggable challenge handlers (DNS-01, HTTP-01) and pluggable certificate storage backends (MongoDB, in-memory, or your own).
+
+### 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
+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'; // LetsEncrypt environment
+  challengeHandlers: IChallengeHandler[];  // At least one handler required
+  challengePriority?: string[];            // e.g. ['dns-01', 'http-01']
+  retryOptions?: {                         // Optional retry/backoff config
+    retries?: number;
+    factor?: number;
+    minTimeoutMs?: number;
+    maxTimeoutMs?: number;
+  };
+}
 ```
 
-## Usage
+### Getting Certificates
+
+```typescript
+// Standard certificate for a single domain
+const cert = await smartAcme.getCertificateForDomain('example.com');
+
+// Include wildcard certificate (requires DNS-01 handler)
+const certWithWildcard = await smartAcme.getCertificateForDomain('example.com', {
+  includeWildcard: true,
+});
 
-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.
+// Request wildcard only
+const wildcardCert = await smartAcme.getCertificateForDomain('*.example.com');
+```
 
-### Table of Contents
+Certificates are automatically cached and reused when still valid. Renewal happens automatically when a certificate is within 10 days of expiration.
 
-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)
+### Certificate Object
 
-### Setting Up Your Project
+The returned `SmartacmeCert` object has these properties:
 
-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.
+| Property     | Type     | Description                          |
+|-------------|----------|--------------------------------------|
+| `id`        | `string` | Unique certificate identifier        |
+| `domainName`| `string` | Domain the cert is issued for        |
+| `publicKey` | `string` | PEM-encoded certificate              |
+| `privateKey`| `string` | PEM-encoded private key              |
+| `csr`       | `string` | Certificate Signing Request          |
+| `created`   | `number` | Timestamp of creation                |
+| `validUntil`| `number` | Timestamp of expiration              |
 
-### Creating a SmartAcme Instance
+## Certificate Managers
 
-Start by importing the `SmartAcme` class and any built-in handlers you plan to use. For example, to use DNS-01 via Cloudflare:
+SmartAcme uses the `ICertManager` interface for pluggable certificate storage.
 
-```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';
+### MongoCertManager
 
-// Create a Cloudflare account client with your API token
-const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_TOKEN');
+Persistent storage backed by MongoDB using `@push.rocks/smartdata`:
 
-// Initialize a certificate manager (e.g., MongoDB)
-const certManager = new MongoCertManager({
-  mongoDbUrl: 'mongodb://yourmongoURL',
-  mongoDbName: 'yourDbName',
-  mongoDbPass: 'yourDbPassword',
-});
+```typescript
+import { certmanagers } from '@push.rocks/smartacme';
 
-// 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
+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 } from '@push.rocks/smartacme';
+import { 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 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.
+SmartAcme ships with three built-in ACME challenge handlers. All implement `IChallengeHandler<T>`.
 
-### Managing Certificates
+### 🌐 Dns01Handler
 
-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.
+Uses Cloudflare (or any `IConvenientDnsProvider`) to set and remove DNS TXT records for `dns-01` challenges:
 
 ```typescript
-import { MongoCertManager } from '@push.rocks/smartacme';
+import { handlers } from '@push.rocks/smartacme';
+import * as cloudflare from '@apiclient.xyz/cloudflare';
 
-const certManager = new MongoCertManager({
-  mongoDbUrl: 'mongodb://yourmongoURL',
-  mongoDbName: 'yourDbName',
-  mongoDbPass: 'yourDbPassword',
-});
+const cfAccount = new cloudflare.CloudflareAccount('YOUR_CF_TOKEN');
+const dnsHandler = new handlers.Dns01Handler(cfAccount);
 ```
 
-SmartAcme uses the `ICertManager` interface for certificate storage. Two built-in implementations are available:
+DNS-01 is required for wildcard certificates and works regardless of server accessibility.
 
-- **MemoryCertManager**
-  - In-memory storage, suitable for testing or ephemeral use.
-  - Import example:
-    ```typescript
-    import { MemoryCertManager } from '@push.rocks/smartacme';
-    const certManager = new MemoryCertManager();
-    ```
+### 📁 Http01Webroot
 
-- **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',
-    });
-    ```
-
-#### Custom Certificate Managers
-
-To implement a custom certificate manager, implement the `ICertManager` interface and pass it to `SmartAcme`:
+Writes challenge response files to a filesystem webroot for `http-01` validation:
 
 ```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 { handlers } from '@push.rocks/smartacme';
 
-// Use your custom manager:
-const customManager = new MyCustomCertManager();
-const smartAcme = new SmartAcme({
-  accountEmail: 'youremail@example.com',
-  certManager: customManager,
-  environment: 'integration',
-  challengeHandlers: [], // add your handlers
+const httpHandler = new handlers.Http01Webroot({
+  webroot: '/var/www/html',
 });
 ```
 
-### Environmental Considerations
+The handler writes to `<webroot>/.well-known/acme-challenge/<token>` and cleans up after validation.
 
-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.
+### 🧠 Http01MemoryHandler
 
-### 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 using a DNS-01 handler:
+In-memory HTTP-01 handler — stores challenge tokens in memory and serves them via `handleRequest()`:
 
 ```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'),
-  });
+import { handlers } from '@push.rocks/smartacme';
 
-  const smartAcmeInstance = new SmartAcme({
-    accountEmail: 'youremail@example.com',
-    certManager,
-    environment: 'integration',
-    challengeHandlers: [new Dns01Handler(cloudflareAccount)],
-  });
+const memHandler = new handlers.Http01MemoryHandler();
+
+// Integrate with any HTTP server (Express, Koa, raw http, etc.)
+app.use((req, res, next) => memHandler.handleRequest(req, res, next));
+```
+
+Perfect for serverless or container environments where filesystem access is limited.
+
+### Custom Challenge Handler
+
+Implement `IChallengeHandler<T>` for custom challenge types:
 
-  await smartAcmeInstance.start();
+```typescript
+import type { IChallengeHandler } from '@push.rocks/smartacme';
 
-  const myDomain = 'example.com';
-  const myCert = await smartAcmeInstance.getCertificateForDomain(myDomain);
-  console.log('Certificate:', myCert);
+interface MyChallenge {
+  type: string;
+  token: string;
+  keyAuthorization: string;
+}
 
-  await smartAcmeInstance.stop();
+class MyHandler implements IChallengeHandler<MyChallenge> {
+  getSupportedTypes(): string[] { return ['http-01']; }
+  async prepare(ch: MyChallenge): Promise<void> { /* ... */ }
+  async cleanup(ch: MyChallenge): Promise<void> { /* ... */ }
+  async checkWetherDomainIsSupported(domain: string): Promise<boolean> { return true; }
 }
+```
+
+## Domain Matching
+
+SmartAcme automatically maps subdomains to their base domain for certificate lookups:
 
-main().catch(console.error);
+```typescript
+// subdomain.example.com → certificate for example.com
+// *.example.com → certificate for example.com
+// a.b.example.com → not supported (4+ level domains)
 ```
- 
- ## 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
+## Environment
 
-The certificate object obtained from the `getCertificateForDomain` method has the following properties:
+- **`production`** — Uses LetsEncrypt production servers. Rate limits apply.
+- **`integration`** — Uses LetsEncrypt staging servers. No rate limits, but certificates are not trusted by browsers. Use for testing.
 
-- `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.
+## Complete Example with HTTP-01
+
+```typescript
+import { SmartAcme, certmanagers, handlers } from '@push.rocks/smartacme';
+import * as http from 'http';
 
-### Methods Summary
+// In-memory handler for HTTP-01 challenges
+const memHandler = new handlers.Http01MemoryHandler();
 
-- **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)**: 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.
+// 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);
 
-### Handling Domain Matching
+// 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'],
+});
 
-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.
+await smartAcme.start();
 
-```typescript
-import { SmartacmeCertMatcher } from '@push.rocks/smartacme';
+const cert = await smartAcme.getCertificateForDomain('example.com');
+// Use cert.publicKey and cert.privateKey with your HTTPS server
 
-const certMatcher = new SmartacmeCertMatcher();
-const certDomainName = certMatcher.getCertificateDomainNameByDomainName('subdomain.example.com');
-console.log('Certificate Domain Name:', certDomainName); // Output: example.com
+await smartAcme.stop();
+server.close();
 ```
 
-### Testing
-
-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:
+## Testing
 
 ```bash
 pnpm test
 ```
 
-
-This comprehensive guide ensures you can set up, manage, and test ACME certificates efficiently and effectively using `@push.rocks/smartacme`.
-
----
+Tests use `@git.zone/tstest` with the tapbundle assertion library.
 
 ## 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: '7.3.4',
+  version: '9.0.0',
   description: 'A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.'
 }

package/ts/acme/acme.classes.account.ts

@@ -0,0 +1,45 @@
+import type { AcmeHttpClient } from './acme.classes.http-client.js';
+import type { IAcmeAccount, IAcmeAccountCreateRequest } from './acme.interfaces.js';
+
+/**
+ * ACME account management - registration and key management
+ */
+export class AcmeAccount {
+  private httpClient: AcmeHttpClient;
+  private accountUrl: string | null = null;
+
+  constructor(httpClient: AcmeHttpClient) {
+    this.httpClient = httpClient;
+  }
+
+  /**
+   * Register or retrieve an ACME account.
+   * Uses JWK (not kid) since account URL is not yet known.
+   * Captures account URL from Location header for subsequent requests.
+   */
+  async create(request: IAcmeAccountCreateRequest): Promise<IAcmeAccount> {
+    const dir = await this.httpClient.getDirectory();
+    const response = await this.httpClient.signedRequest(dir.newAccount, request, {
+      useJwk: true,
+    });
+
+    // Capture account URL from Location header (used as kid for future requests)
+    const location = response.headers['location'];
+    if (location) {
+      this.accountUrl = location;
+      this.httpClient.kid = location;
+    }
+
+    return response.data as IAcmeAccount;
+  }
+
+  /**
+   * Get the account URL (kid) for use in JWS headers
+   */
+  getAccountUrl(): string {
+    if (!this.accountUrl) {
+      throw new Error('Account not yet created - call create() first');
+    }
+    return this.accountUrl;
+  }
+}

package/ts/acme/acme.classes.challenge.ts

@@ -0,0 +1,45 @@
+import * as crypto from 'node:crypto';
+import { AcmeCrypto } from './acme.classes.crypto.js';
+import type { AcmeHttpClient } from './acme.classes.http-client.js';
+import type { IAcmeChallenge } from './acme.interfaces.js';
+
+/**
+ * ACME challenge operations - key authorization computation and challenge completion
+ */
+export class AcmeChallengeManager {
+  private httpClient: AcmeHttpClient;
+  private accountKeyPem: string;
+
+  constructor(httpClient: AcmeHttpClient, accountKeyPem: string) {
+    this.httpClient = httpClient;
+    this.accountKeyPem = accountKeyPem;
+  }
+
+  /**
+   * Compute the key authorization for a challenge.
+   * For http-01: returns `token.thumbprint`
+   * For dns-01: returns `base64url(sha256(token.thumbprint))`
+   *
+   * This is a synchronous, pure-crypto computation.
+   */
+  getKeyAuthorization(challenge: IAcmeChallenge): string {
+    const jwk = AcmeCrypto.getJwk(this.accountKeyPem);
+    const thumbprint = AcmeCrypto.getJwkThumbprint(jwk);
+    const keyAuth = `${challenge.token}.${thumbprint}`;
+
+    if (challenge.type === 'dns-01') {
+      // DNS-01 uses base64url(SHA-256(keyAuthorization))
+      return crypto.createHash('sha256').update(keyAuth).digest().toString('base64url');
+    }
+
+    // HTTP-01 and others use the raw key authorization
+    return keyAuth;
+  }
+
+  /**
+   * Notify the ACME server to validate a challenge (POST {} to challenge URL)
+   */
+  async complete(challenge: IAcmeChallenge): Promise<void> {
+    await this.httpClient.signedRequest(challenge.url, {});
+  }
+}