Files

Juergen Kunz cf4b758800 BREAKING CHANGE(acme): Replace external acme-client with a built-in RFC8555-compliant ACME implementation and update public APIs accordingly

2026-02-15 20:20:46 +00:00

10 KiB

Raw Blame History

@push.rocks/smartacme

A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power. 🔒

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/smartacme

Ensure your project uses TypeScript and ECMAScript Modules (ESM).

Usage

@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

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();

SmartAcme Options

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;
  };
}

Getting Certificates

// 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,
});

// Request wildcard only
const wildcardCert = await smartAcme.getCertificateForDomain('*.example.com');

Certificates are automatically cached and reused when still valid. Renewal happens automatically when a certificate is within 10 days of expiration.

Certificate Object

The returned SmartacmeCert object has these properties:

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

Certificate Managers

SmartAcme uses the ICertManager interface for pluggable certificate storage.

MongoCertManager

Persistent storage backed by MongoDB using @push.rocks/smartdata:

import { certmanagers } from '@push.rocks/smartacme';

const certManager = new certmanagers.MongoCertManager({
  mongoDbUrl: 'mongodb://localhost:27017',
  mongoDbName: 'myapp',
  mongoDbPass: 'secret',
});

MemoryCertManager

In-memory storage, ideal for testing or ephemeral workloads:

import { certmanagers } from '@push.rocks/smartacme';

const certManager = new certmanagers.MemoryCertManager();

Custom Certificate Manager

Implement the ICertManager interface for your own storage backend:

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 */ }
}

Challenge Handlers

SmartAcme ships with three built-in ACME challenge handlers. All implement IChallengeHandler<T>.

🌐 Dns01Handler

Uses Cloudflare (or any IConvenientDnsProvider) to set and remove DNS TXT records for dns-01 challenges:

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:

import { handlers } from '@push.rocks/smartacme';

const httpHandler = new handlers.Http01Webroot({
  webroot: '/var/www/html',
});

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():

import { handlers } from '@push.rocks/smartacme';

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:

import type { IChallengeHandler } from '@push.rocks/smartacme';

interface MyChallenge {
  type: string;
  token: string;
  keyAuthorization: string;
}

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:

// subdomain.example.com → certificate for example.com
// *.example.com → certificate for example.com
// a.b.example.com → not supported (4+ level domains)

Environment

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.

Complete Example with HTTP-01

import { SmartAcme, certmanagers, handlers } from '@push.rocks/smartacme';
import * as http from 'http';

// In-memory handler for HTTP-01 challenges
const memHandler = new handlers.Http01MemoryHandler();

// 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);

// 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'],
});

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();

Testing

pnpm test

Tests use @git.zone/tstest with the tapbundle assertion library.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the 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 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.

10 KiB Raw Blame History