{"id":23962636,"url":"https://github.com/publishlab/node-acme-client","last_synced_at":"2025-05-15T17:08:15.728Z","repository":{"id":25254069,"uuid":"103565864","full_name":"publishlab/node-acme-client","owner":"publishlab","description":"Simple and unopinionated ACME client for Node.js","archived":false,"fork":false,"pushed_at":"2024-07-17T12:45:50.000Z","size":530,"stargazers_count":283,"open_issues_count":16,"forks_count":58,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-28T09:37:54.628Z","etag":null,"topics":["acme","acme-client","letsencrypt","nodejs","rfc8555"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/publishlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-14T18:11:27.000Z","updated_at":"2025-04-27T09:42:00.000Z","dependencies_parsed_at":"2024-02-03T17:44:57.585Z","dependency_job_id":"0cc1af66-238c-435d-9de9-ac8a9ceb1c7b","html_url":"https://github.com/publishlab/node-acme-client","commit_stats":{"total_commits":246,"total_committers":8,"mean_commits":30.75,"dds":0.03252032520325199,"last_synced_commit":"4335c1e9dd5cd23c8001d486b05bcae847b32783"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publishlab%2Fnode-acme-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publishlab%2Fnode-acme-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publishlab%2Fnode-acme-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/publishlab%2Fnode-acme-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/publishlab","download_url":"https://codeload.github.com/publishlab/node-acme-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253128005,"owners_count":21858372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acme","acme-client","letsencrypt","nodejs","rfc8555"],"created_at":"2025-01-06T20:36:02.565Z","updated_at":"2025-05-15T17:08:10.699Z","avatar_url":"https://github.com/publishlab.png","language":"JavaScript","readme":"# acme-client [![test](https://github.com/publishlab/node-acme-client/actions/workflows/tests.yml/badge.svg)](https://github.com/publishlab/node-acme-client/actions/workflows/tests.yml)\n\n*A simple and unopinionated ACME client.*\n\nThis module is written to handle communication with a Boulder/Let's Encrypt-style ACME API.\n\n* RFC 8555 - Automatic Certificate Management Environment (ACME): [https://datatracker.ietf.org/doc/html/rfc8555](https://datatracker.ietf.org/doc/html/rfc8555)\n* Boulder divergences from ACME: [https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md](https://github.com/letsencrypt/boulder/blob/master/docs/acme-divergences.md)\n\n## Compatibility\n\n| acme-client | Node.js |                                           |\n| ----------- | ------- | ----------------------------------------- |\n| v5.x        | \u003e= v16  | [Upgrade guide](docs/upgrade-v5.md)       |\n| v4.x        | \u003e= v10  | [Changelog](CHANGELOG.md#v400-2020-05-29) |\n| v3.x        | \u003e= v8   | [Changelog](CHANGELOG.md#v300-2019-07-13) |\n| v2.x        | \u003e= v4   | [Changelog](CHANGELOG.md#v200-2018-04-02) |\n| v1.x        | \u003e= v4   | [Changelog](CHANGELOG.md#v100-2017-10-20) |\n\n## Table of contents\n\n* [Installation](#installation)\n* [Usage](#usage)\n    * [Directory URLs](#directory-urls)\n    * [External account binding](#external-account-binding)\n    * [Specifying the account URL](#specifying-the-account-url)\n* [Cryptography](#cryptography)\n    * [Legacy .forge interface](#legacy-forge-interface)\n* [Auto mode](#auto-mode)\n    * [Challenge priority](#challenge-priority)\n    * [Internal challenge verification](#internal-challenge-verification)\n* [API](#api)\n* [HTTP client defaults](#http-client-defaults)\n* [Debugging](#debugging)\n* [License](#license)\n\n## Installation\n\n```bash\n$ npm install acme-client\n```\n\n## Usage\n\n```js\nconst acme = require('acme-client');\n\nconst accountPrivateKey = '\u003cPEM encoded private key\u003e';\n\nconst client = new acme.Client({\n    directoryUrl: acme.directory.letsencrypt.staging,\n    accountKey: accountPrivateKey,\n});\n```\n\n### Directory URLs\n\n```js\nacme.directory.buypass.staging;\nacme.directory.buypass.production;\n\nacme.directory.google.staging;\nacme.directory.google.production;\n\nacme.directory.letsencrypt.staging;\nacme.directory.letsencrypt.production;\n\nacme.directory.zerossl.production;\n```\n\n### External account binding\n\nTo enable [external account binding](https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.4) when creating your ACME account, provide your KID and HMAC key to the client constructor.\n\n```js\nconst client = new acme.Client({\n    directoryUrl: 'https://acme-provider.example.com/directory-url',\n    accountKey: accountPrivateKey,\n    externalAccountBinding: {\n        kid: 'YOUR-EAB-KID',\n        hmacKey: 'YOUR-EAB-HMAC-KEY',\n    },\n});\n```\n\n### Specifying the account URL\n\nDuring 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.\n\nIn 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.\n\n```js\nconst client = new acme.Client({\n    directoryUrl: acme.directory.letsencrypt.staging,\n    accountKey: accountPrivateKey,\n    accountUrl: 'https://acme-v02.api.letsencrypt.org/acme/acct/12345678',\n});\n```\n\nYou can fetch the clients current account URL, either after creating an account or supplying it through the constructor, using `getAccountUrl()`:\n\n```js\nconst myAccountUrl = client.getAccountUrl();\n```\n\n## Cryptography\n\nFor key pairs `acme-client` utilizes native Node.js cryptography APIs, supporting signing and generation of both RSA and ECDSA keys. The module [@peculiar/x509](https://www.npmjs.com/package/@peculiar/x509) is used to generate and parse Certificate Signing Requests.\n\nThese utility methods are exposed through `.crypto`.\n\n* **Documentation: [docs/crypto.md](docs/crypto.md)**\n\n```js\nconst privateRsaKey = await acme.crypto.createPrivateRsaKey();\nconst privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();\n\nconst [certificateKey, certificateCsr] = await acme.crypto.createCsr({\n    altNames: ['example.com', '*.example.com'],\n});\n```\n\n### Legacy `.forge` interface\n\nThe 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`.\n\nYou should consider migrating to the new `.crypto` API at your earliest convenience. More details can be found in the [acme-client v5 upgrade guide](docs/upgrade-v5.md).\n\n* **Documentation: [docs/forge.md](docs/forge.md)**\n\n## Auto mode\n\nFor 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.\n\n* **Documentation: [docs/client.md#AcmeClient+auto](docs/client.md#AcmeClient+auto)**\n* **Full example: [examples/auto.js](examples/auto.js)**\n\n```js\nconst autoOpts = {\n    csr: '\u003cPEM encoded CSR\u003e',\n    email: 'test@example.com',\n    termsOfServiceAgreed: true,\n    challengeCreateFn: async (authz, challenge, keyAuthorization) =\u003e {},\n    challengeRemoveFn: async (authz, challenge, keyAuthorization) =\u003e {},\n};\n\nconst certificate = await client.auto(autoOpts);\n```\n\n### Challenge priority\n\nWhen 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`\".\n\nWhile 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](https://letsencrypt.org/docs/challenge-types/).\n\nTo modify challenge priority, provide a list of challenge types in `challengePriority`:\n\n```js\nawait client.auto({\n    ...,\n    challengePriority: ['http-01', 'dns-01'],\n});\n```\n\n### Internal challenge verification\n\nWhen 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.\n\nIf internal challenge validation needs to travel through an HTTP proxy, see [HTTP client defaults](#http-client-defaults).\n\nTo completely disable `acme-client`s internal challenge verification, enable `skipChallengeVerification`:\n\n```js\nawait client.auto({\n    ...,\n    skipChallengeVerification: true,\n});\n```\n\n## API\n\nFor more fine-grained control you can interact with the ACME API using the methods documented below.\n\n* **Documentation: [docs/client.md](docs/client.md)**\n* **Full example: [examples/api.js](examples/api.js)**\n\n```js\nconst account = await client.createAccount({\n    termsOfServiceAgreed: true,\n    contact: ['mailto:test@example.com'],\n});\n\nconst order = await client.createOrder({\n    identifiers: [\n        { type: 'dns', value: 'example.com' },\n        { type: 'dns', value: '*.example.com' },\n    ],\n});\n```\n\n## HTTP client defaults\n\nThis module uses [axios](https://github.com/axios/axios) when communicating with the ACME HTTP API, and exposes the client instance through `.axios`.\n\nFor example, should you need to change the default axios configuration to route requests through an HTTP proxy, this can be achieved as follows:\n\n```js\nconst acme = require('acme-client');\n\nacme.axios.defaults.proxy = {\n    host: '127.0.0.1',\n    port: 9000,\n};\n```\n\nA complete list of axios options and documentation can be found at:\n\n* [https://github.com/axios/axios#request-config](https://github.com/axios/axios#request-config)\n* [https://github.com/axios/axios#custom-instance-defaults](https://github.com/axios/axios#custom-instance-defaults)\n\n## Debugging\n\nTo 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.\n\nSetting a logger function may for example be useful for passing messages on to another logging system, or just dumping them to the console.\n\n```js\nacme.setLogger((message) =\u003e {\n    console.log(message);\n});\n```\n\nDebugging to the console can also be enabled through [debug](https://www.npmjs.com/package/debug) by setting an environment variable.\n\n```bash\nDEBUG=acme-client node index.js\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpublishlab%2Fnode-acme-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpublishlab%2Fnode-acme-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpublishlab%2Fnode-acme-client/lists"}