acme-client

library0jsnpmunverified

acme-client is a simple and unopinionated Node.js library designed to interact with ACME (Automatic Certificate Management Environment) APIs, such as those provided by Let's Encrypt, Buypass, Google, and ZeroSSL. It adheres to RFC 8555 for ACME protocol communication. The current stable version is 5.4.0, requiring Node.js >= 16.0.0. The library primarily focuses on certificate management tasks, including account registration, order processing, and challenge fulfillment, supporting both RSA and ECDSA keys through native Node.js cryptography. It differentiates itself by being unopinionated and providing direct control over the ACME workflow, rather than an 'auto-mode' by default (though auto mode is available), and ships with TypeScript types for improved developer experience. While major versions have specific Node.js requirements, the project appears to release updates as needed, rather than on a fixed cadence.

auth-security http-networking

npm install acme-client

github ↗package ↗

INSTALL

IMPORT

SIG · ACME-CLIENT

acme-client

auth-securityjavascriptv0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ import { Client } from 'acme-client';

✗ const Client = require('acme-client').Client;

While CommonJS `require` works for `acme-client`, the destructuring `const { Client } = require('acme-client');` is the idiomatic way for named exports in CJS.

directory

✓ import { directory } from 'acme-client';

✗ import directory from 'acme-client/directory';

The `directory` object, containing predefined ACME server URLs (e.g., Let's Encrypt, Buypass), is a named export from the main package, not a default export or a separate submodule.

AcmeClient

✓ import type { Client as AcmeClient } from 'acme-client';

For TypeScript users, importing types is crucial for proper type checking and IDE auto-completion. The `Client` class can be aliased for clarity if desired.

Demonstrates how to initialize the ACME client, create a new private key for the ACME account, and register or retrieve an ACME account from the Let's Encrypt staging environment.

import { Client, directory } from 'acme-client'; import { createPrivateKey } from 'crypto'; async function runAcmeClient() { // In a real application, load this from a secure source or generate it once const accountPrivateKey = createPrivateKey({ type: 'rsa', modulusLength: 2048, publicKeyEncoding: { type: 'spki', format: 'pem' }, privateKeyEncoding: { type: 'pkcs8', format: 'pem' } }).export({ type: 'pkcs8', format: 'pem' }).toString(); console.log('Using account private key (truncated):', accountPrivateKey.substring(0, 50) + '...'); const client = new Client({ directoryUrl: directory.letsencrypt.staging, accountKey: accountPrivateKey, }); console.log('ACME client initialized with Let\'s Encrypt staging directory.'); // Example: Register a new ACME account or get existing one const account = await client.createAccount({ termsOfServiceAgreed: true, contact: ['mailto:test@example.com'], }); console.log('ACME account registered/fetched:', account); const accountUrl = client.getAccountUrl(); console.log('Account URL:', accountUrl); // In a real scenario, you'd now proceed to create an order, generate a CSR, and fulfill challenges. // This quickstart only covers client initialization and account registration. } runAcmeClient().catch(console.error);

Debug

Known issues

breakingVersion 5.x of `acme-client` requires Node.js version 16 or newer. Older Node.js versions (v10, v8, v4) are compatible with earlier major versions (v4.x, v3.x, v2.x/v1.x respectively).

fix

Upgrade your Node.js runtime to version 16 or later, or downgrade `acme-client` to a compatible major version for your Node.js environment (e.g., `npm install acme-client@4`).

affects: >=5.0.0

breakingOlder versions of `acme-client` (pre-v5) might have different API signatures or return types. Always consult the upgrade guide or changelog when moving between major versions.

fix

Refer to the `docs/upgrade-v5.md` for specific changes when migrating from `v4.x` to `v5.x`. Check `CHANGELOG.md` for other major version transitions.

affects: >=5.0.0

gotchaWhen using external account binding (EAB), ensure that the `kid` and `hmacKey` are correctly provided in the client constructor. Incorrect EAB credentials will lead to account creation or update failures.

fix

Double-check the `externalAccountBinding` object for typos and ensure the `kid` and `hmacKey` match those provided by your ACME provider (e.g., ZeroSSL, Google ACME).

affects: >=1.0.0

gotchaIt's critical to store ACME account private keys securely and persist them across application restarts. Losing the account key means losing control over certificates associated with that account.

fix

Implement robust key management practices: generate keys once, store them encrypted in a persistent, secure location (e.g., file system, database, KMS), and load them at application startup. Avoid regenerating keys on every run.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_OSSL_EVP_UNSUPPORTED: Unsupported cipher algorithm

This error typically indicates an incompatibility between Node.js's OpenSSL version and the key or certificate format being processed, often due to deprecated algorithms or features.

fix

Ensure your Node.js version is up-to-date (v16+ is recommended for `acme-client` v5+). If generating keys, use modern algorithms (e.g., RSA 2048-bit or ECDSA P-256) and standard encodings (PKCS8 for private keys, SPKI for public keys).

Error: Invalid response from ACME server (status: 400, type: urn:ietf:params:acme:error:malformed)

The ACME server rejected a request due to malformed data, often an issue with the request payload, headers, or a cryptographic signature.

fix

Verify that all required fields are present and correctly formatted in your ACME client calls. Check for special characters in contact emails, ensure private keys are valid PEM, and that account/order URLs are correct. Enable debug logging (`acme.setLogger`) to see the full request and response for more details.

Error: Account terms of service must be agreed

The ACME server requires explicit agreement to its terms of service before an account can be registered or used.

fix

When calling `client.createAccount()`, ensure you set `termsOfServiceAgreed: true`. You should only do this after your application (or end-user) has reviewed and accepted the current terms of service.

Upgrade

Version history

0latest on npm

Audit

Dependencies

@peculiar/x509requiredUsed internally for generating and parsing Certificate Signing Requests (CSRs).

Agent activity

58 hits · last 30 days

node