ACME Client for Node.js

Common errors

• ERR_OSSL_EVP_UNSUPPORTED: Unsupported cipher algorithm

  cause 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)

  cause 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

  cause 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.

Warnings

• breaking Version 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`).
• breaking Older 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.
• gotcha When 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).
• gotcha It'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.

Install

• npm install acme-client npm
• yarn add acme-client yarn
• pnpm add acme-client pnpm

Imports

• Client
  wrong:

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

  correct:

  import { Client } from 'acme-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
  wrong:

  import directory from 'acme-client/directory';

  correct:

  import { directory } from 'acme-client';

  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.

Quickstart

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