npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

acme-client

v5.4.0

Published

Simple and unopinionated ACME client

Downloads

1,480,423

Readme

acme-client test

A simple and unopinionated ACME client.

This module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.

Compatibility

| acme-client | Node.js | | | ----------- | ------- | ----------------------------------------- | | v5.x | >= v16 | Upgrade guide | | v4.x | >= v10 | Changelog | | v3.x | >= v8 | Changelog | | v2.x | >= v4 | Changelog | | v1.x | >= v4 | Changelog |

Table of contents

Installation

$ npm install acme-client

Usage

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

const accountPrivateKey = '<PEM encoded private key>';

const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
});

Directory URLs

acme.directory.buypass.staging;
acme.directory.buypass.production;

acme.directory.google.staging;
acme.directory.google.production;

acme.directory.letsencrypt.staging;
acme.directory.letsencrypt.production;

acme.directory.zerossl.production;

External account binding

To enable external account binding when creating your ACME account, provide your KID and HMAC key to the client constructor.

const client = new acme.Client({
    directoryUrl: 'https://acme-provider.example.com/directory-url',
    accountKey: accountPrivateKey,
    externalAccountBinding: {
        kid: 'YOUR-EAB-KID',
        hmacKey: 'YOUR-EAB-HMAC-KEY',
    },
});

Specifying the account URL

During the ACME account creation process, the server will check the supplied account key and either create a new account if the key is unused, or return the existing ACME account bound to that key.

In some cases, for example with some EAB providers, this account creation step may be prohibited and might require you to manually specify the account URL beforehand. This can be done through accountUrl in the client constructor.

const client = new acme.Client({
    directoryUrl: acme.directory.letsencrypt.staging,
    accountKey: accountPrivateKey,
    accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678',
});

You can fetch the clients current account URL, either after creating an account or supplying it through the constructor, using getAccountUrl():

const myAccountUrl = client.getAccountUrl();

Cryptography

For key pairs acme-client utilizes native Node.js cryptography APIs, supporting signing and generation of both RSA and ECDSA keys. The module @peculiar/x509 is used to generate and parse Certificate Signing Requests.

These utility methods are exposed through .crypto.

const privateRsaKey = await acme.crypto.createPrivateRsaKey();
const privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();

const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
    altNames: ['example.com', '*.example.com'],
});

Legacy .forge interface

The legacy node-forge crypto interface is still available for backward compatibility, however this interface is now considered deprecated and will be removed in a future major version of acme-client.

You should consider migrating to the new .crypto API at your earliest convenience. More details can be found in the acme-client v5 upgrade guide.

Auto mode

For convenience an auto() method is included in the client that takes a single config object. This method will handle the entire process of getting a certificate for one or multiple domains.

const autoOpts = {
    csr: '<PEM encoded CSR>',
    email: '[email protected]',
    termsOfServiceAgreed: true,
    challengeCreateFn: async (authz, challenge, keyAuthorization) => {},
    challengeRemoveFn: async (authz, challenge, keyAuthorization) => {},
};

const certificate = await client.auto(autoOpts);

Challenge priority

When ordering a certificate using auto mode, acme-client uses a priority list when selecting challenges to respond to. Its default value is ['http-01', 'dns-01'] which translates to "use http-01 if any challenges exist, otherwise fall back to dns-01".

While most challenges can be validated using the method of your choosing, please note that wildcard certificates can only be validated through dns-01. More information regarding Let's Encrypt challenge types can be found here.

To modify challenge priority, provide a list of challenge types in challengePriority:

await client.auto({
    ...,
    challengePriority: ['http-01', 'dns-01'],
});

Internal challenge verification

When using auto mode, acme-client will first validate that challenges are satisfied internally before completing the challenge at the ACME provider. In some cases (firewalls, etc) this internal challenge verification might not be possible to complete.

If internal challenge validation needs to travel through an HTTP proxy, see HTTP client defaults.

To completely disable acme-clients internal challenge verification, enable skipChallengeVerification:

await client.auto({
    ...,
    skipChallengeVerification: true,
});

API

For more fine-grained control you can interact with the ACME API using the methods documented below.

const account = await client.createAccount({
    termsOfServiceAgreed: true,
    contact: ['mailto:[email protected]'],
});

const order = await client.createOrder({
    identifiers: [
        { type: 'dns', value: 'example.com' },
        { type: 'dns', value: '*.example.com' },
    ],
});

HTTP client defaults

This module uses axios when communicating with the ACME HTTP API, and exposes the client instance through .axios.

For example, should you need to change the default axios configuration to route requests through an HTTP proxy, this can be achieved as follows:

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

acme.axios.defaults.proxy = {
    host: '127.0.0.1',
    port: 9000,
};

A complete list of axios options and documentation can be found at:

Debugging

To get a better grasp of what acme-client is doing behind the scenes, you can either pass it a logger function, or enable debugging through an environment variable.

Setting a logger function may for example be useful for passing messages on to another logging system, or just dumping them to the console.

acme.setLogger((message) => {
    console.log(message);
});

Debugging to the console can also be enabled through debug by setting an environment variable.

DEBUG=acme-client node index.js

License

MIT