@certd/acme-client 1.39.12 → 1.39.14

package/dist/axios.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Defaults
+ */
+declare const instance: import("axios").AxiosInstance;
+/**
+ * Export instance
+ */
+export default instance;

package/{src → dist}/axios.js

@@ -1,26 +1,23 @@
+// @ts-nocheck
 /**
  * Axios instance
  */
 import axios from 'axios';
 import { parseRetryAfterHeader } from './util.js';
 const { AxiosError } = axios;
-import {getGlobalAgents, HttpError} from '@certd/basic'
+import { getGlobalAgents, HttpError } from '@certd/basic';
 import { log } from './logger.js';
 /**
  * Defaults
  */
-
 const instance = axios.create();
-
 /* Default User-Agent */
 instance.defaults.headers.common['User-Agent'] = `@certd/acme-client`;
-
 /* Default ACME settings */
 instance.defaults.acmeSettings = {
     httpChallengePort: 80,
     httpsChallengePort: 443,
     tlsAlpnChallengePort: 443,
-
     retryMaxAttempts: 3,
     retryDefaultDelay: 3,
 };
@@ -34,15 +31,12 @@ instance.defaults.acmeSettings = {
  * https://github.com/axios/axios/issues/1180
  * https://stackoverflow.com/questions/42677387
  */
-
 instance.defaults.adapter = 'http';
-
 /**
  * Retry requests on server errors or when rate limited
  *
  * https://datatracker.ietf.org/doc/html/rfc8555#section-6.6
  */
-
 function isRetryableError(error) {
     return (error.code !== 'ECONNABORTED')
         && (error.code !== 'ERR_NOCK_NO_MATCH')
@@ -50,7 +44,6 @@ function isRetryableError(error) {
             || (error.response.status === 429)
             || ((error.response.status >= 500) && (error.response.status <= 599)));
 }
-
 /* https://github.com/axios/axios/blob/main/lib/core/settle.js */
 function validateStatus(response) {
     if (!response) {
@@ -63,25 +56,15 @@ function validateStatus(response) {
     if (!response.status || !validator || validator(response.status)) {
         return response;
     }
-
-    const err = new AxiosError(
-        `Request failed with status code ${response.status}`,
-        (Math.floor(response.status / 100) === 4) ? AxiosError.ERR_BAD_REQUEST : AxiosError.ERR_BAD_RESPONSE,
-        response.config,
-        response.request,
-        response,
-    );
-
+    const err = new AxiosError(`Request failed with status code ${response.status}`, (Math.floor(response.status / 100) === 4) ? AxiosError.ERR_BAD_REQUEST : AxiosError.ERR_BAD_RESPONSE, response.config, response.request, response);
     throw new HttpError(err);
 }
-
 /* Pass all responses through the error interceptor */
 instance.interceptors.request.use((config) => {
     if (!('retryValidateStatus' in config)) {
         config.retryValidateStatus = config.validateStatus;
     }
     config.validateStatus = () => false;
-
     const agents = getGlobalAgents();
     // if (config.skipSslVerify) {
     //     logger.info('跳过SSL验证');
@@ -93,53 +76,42 @@ instance.interceptors.request.use((config) => {
     config.proxy = false; // 必须 否则还会走一层代理，
     return config;
 });
-
 /* Handle request retries if applicable */
 instance.interceptors.response.use(null, async (error) => {
     const { config, response } = error;
-
     if (!config) {
         return Promise.reject(new HttpError(error));
     }
-
     /* Pick up errors we want to retry */
     if (isRetryableError(error)) {
         const { retryMaxAttempts, retryDefaultDelay } = instance.defaults.acmeSettings;
         config.retryAttempt = ('retryAttempt' in config) ? (config.retryAttempt + 1) : 1;
-
         if (config.retryAttempt <= retryMaxAttempts) {
             const code = response ? `HTTP ${response.status}` : error.code;
             log(`Caught ${code}, retry attempt ${config.retryAttempt}/${retryMaxAttempts} to URL ${config.url}`);
-
             const retryAfter = (retryDefaultDelay * config.retryAttempt);
             /* Attempt to parse Retry-After header, fallback to default delay */
             const headerRetryAfter = response ? parseRetryAfterHeader(response.headers['retry-after']) : 0;
-
             if (headerRetryAfter > 0) {
                 const waitMinutes = (headerRetryAfter / 60).toFixed(1);
                 log(`Found retry-after response header with value: ${response.headers['retry-after']}, waiting ${waitMinutes} minutes`);
                 log(JSON.stringify(response.data));
                 return Promise.reject(new HttpError(error));
             }
-
             log(`waiting ${retryAfter} seconds`);
-
             /* Wait and retry the request */
             await new Promise((resolve) => { setTimeout(resolve, (retryAfter * 1000)); });
             log(`Retrying request to URL ${config.url}`);
             return instance(config);
         }
     }
-
     if (!response) {
         return Promise.reject(new HttpError(error));
     }
     /* Validate and return response */
     return validateStatus(response);
 });
-
 /**
  * Export instance
  */
-
 export default instance;

package/dist/client.d.ts

@@ -0,0 +1,396 @@
+/**
+ * AcmeClient
+ *
+ * @class
+ * @param {object} opts
+ * @param {string} opts.directoryUrl ACME directory URL
+ * @param {buffer|string} opts.accountKey PEM encoded account private key
+ * @param {string} [opts.accountUrl] Account URL, default: `null`
+ * @param {object} [opts.externalAccountBinding]
+ * @param {string} [opts.externalAccountBinding.kid] External account binding KID
+ * @param {string} [opts.externalAccountBinding.hmacKey] External account binding HMAC key
+ * @param {number} [opts.backoffAttempts] Maximum number of backoff attempts, default: `10`
+ * @param {number} [opts.backoffMin] Minimum backoff attempt delay in milliseconds, default: `5000`
+ * @param {number} [opts.backoffMax] Maximum backoff attempt delay in milliseconds, default: `30000`
+ *
+ * @example Create ACME client instance
+ * ```js
+ * const client = new acme.Client({
+ *     directoryUrl: acme.directory.letsencrypt.staging,
+ *     accountKey: 'Private key goes here',
+ * });
+ * ```
+ *
+ * @example Create ACME client instance
+ * ```js
+ * const client = new acme.Client({
+ *     directoryUrl: acme.directory.letsencrypt.staging,
+ *     accountKey: 'Private key goes here',
+ *     accountUrl: 'Optional account URL goes here',
+ *     backoffAttempts: 10,
+ *     backoffMin: 5000,
+ *     backoffMax: 30000,
+ * });
+ * ```
+ *
+ * @example Create ACME client with external account binding
+ * ```js
+ * const client = new acme.Client({
+ *     directoryUrl: 'https://acme-provider.example.com/directory-url',
+ *     accountKey: 'Private key goes here',
+ *     externalAccountBinding: {
+ *         kid: 'YOUR-EAB-KID',
+ *         hmacKey: 'YOUR-EAB-HMAC-KEY',
+ *     },
+ * });
+ * ```
+ */
+declare class AcmeClient {
+    sslProvider: any;
+    constructor(opts: any);
+    log(...args: any[]): void;
+    /**
+     * Get Terms of Service URL if available
+     *
+     * @returns {Promise<string|null>} ToS URL
+     *
+     * @example Get Terms of Service URL
+     * ```js
+     * const termsOfService = client.getTermsOfServiceUrl();
+     *
+     * if (!termsOfService) {
+     *     // CA did not provide Terms of Service
+     * }
+     * ```
+     */
+    getTermsOfServiceUrl(): any;
+    /**
+     * Get current account URL
+     *
+     * @returns {string} Account URL
+     * @throws {Error} No account URL found
+     *
+     * @example Get current account URL
+     * ```js
+     * try {
+     *     const accountUrl = client.getAccountUrl();
+     * }
+     * catch (e) {
+     *     // No account URL exists, need to create account first
+     * }
+     * ```
+     */
+    getAccountUrl(): any;
+    /**
+     * Create a new account
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.3
+     *
+     * @param {object} [data] Request data
+     * @returns {Promise<object>} Account
+     *
+     * @example Create a new account
+     * ```js
+     * const account = await client.createAccount({
+     *     termsOfServiceAgreed: true,
+     * });
+     * ```
+     *
+     * @example Create a new account with contact info
+     * ```js
+     * const account = await client.createAccount({
+     *     termsOfServiceAgreed: true,
+     *     contact: ['mailto:test@example.com'],
+     * });
+     * ```
+     */
+    createAccount(data?: {}): any;
+    /**
+     * Update existing account
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.2
+     *
+     * @param {object} [data] Request data
+     * @returns {Promise<object>} Account
+     *
+     * @example Update existing account
+     * ```js
+     * const account = await client.updateAccount({
+     *     contact: ['mailto:foo@example.com'],
+     * });
+     * ```
+     */
+    updateAccount(data?: {}): any;
+    /**
+     * Update account private key
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.5
+     *
+     * @param {buffer|string} newAccountKey New PEM encoded private key
+     * @param {object} [data] Additional request data
+     * @returns {Promise<object>} Account
+     *
+     * @example Update account private key
+     * ```js
+     * const newAccountKey = 'New private key goes here';
+     * const result = await client.updateAccountKey(newAccountKey);
+     * ```
+     */
+    updateAccountKey(newAccountKey: any, data?: {}): Promise<any>;
+    /**
+     * Create a new order
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.4
+     *
+     * @param {object} data Request data
+     * @returns {Promise<object>} Order
+     *
+     * @example Create a new order
+     * ```js
+     * const order = await client.createOrder({
+     *     identifiers: [
+     *         { type: 'dns', value: 'example.com' },
+     *         { type: 'dns', value: 'test.example.com' },
+     *     ],
+     * });
+     * ```
+     */
+    createOrder(data: any): Promise<any>;
+    /**
+     * Refresh order object from CA
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.4
+     *
+     * @param {object} order Order object
+     * @returns {Promise<object>} Order
+     *
+     * @example
+     * ```js
+     * const order = { ... }; // Previously created order object
+     * const result = await client.getOrder(order);
+     * ```
+     */
+    getOrder(order: any): Promise<any>;
+    /**
+     * Finalize order
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.4
+     *
+     * @param {object} order Order object
+     * @param {buffer|string} csr PEM encoded Certificate Signing Request
+     * @returns {Promise<object>} Order
+     *
+     * @example Finalize order
+     * ```js
+     * const order = { ... }; // Previously created order object
+     * const csr = { ... }; // Previously created Certificate Signing Request
+     * const result = await client.finalizeOrder(order, csr);
+     * ```
+     */
+    finalizeOrder(order: any, csr: any): Promise<any>;
+    /**
+     * Get identifier authorizations from order
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.5
+     *
+     * @param {object} order Order
+     * @returns {Promise<object[]>} Authorizations
+     *
+     * @example Get identifier authorizations
+     * ```js
+     * const order = { ... }; // Previously created order object
+     * const authorizations = await client.getAuthorizations(order);
+     *
+     * authorizations.forEach((authz) => {
+     *     const { challenges } = authz;
+     * });
+     * ```
+     */
+    getAuthorizations(order: any): Promise<any[]>;
+    /**
+     * Deactivate identifier authorization
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.2
+     *
+     * @param {object} authz Identifier authorization
+     * @returns {Promise<object>} Authorization
+     *
+     * @example Deactivate identifier authorization
+     * ```js
+     * const authz = { ... }; // Identifier authorization resolved from previously created order
+     * const result = await client.deactivateAuthorization(authz);
+     * ```
+     */
+    deactivateAuthorization(authz: any): Promise<any>;
+    /**
+     * Get key authorization for ACME challenge
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-8.1
+     *
+     * @param {object} challenge Challenge object returned by API
+     * @returns {Promise<string>} Key authorization
+     *
+     * @example Get challenge key authorization
+     * ```js
+     * const challenge = { ... }; // Challenge from previously resolved identifier authorization
+     * const key = await client.getChallengeKeyAuthorization(challenge);
+     *
+     * // Write key somewhere to satisfy challenge
+     * ```
+     */
+    getChallengeKeyAuthorization(challenge: any): Promise<string>;
+    /**
+     * Verify that ACME challenge is satisfied
+     *
+     * @param {object} authz Identifier authorization
+     * @param {object} challenge Authorization challenge
+     * @returns {Promise}
+     *
+     * @example Verify satisfied ACME challenge
+     * ```js
+     * const authz = { ... }; // Identifier authorization
+     * const challenge = { ... }; // Satisfied challenge
+     * await client.verifyChallenge(authz, challenge);
+     * ```
+     */
+    verifyChallenge(authz: any, challenge: any): Promise<any>;
+    /**
+     * Notify CA that challenge has been completed
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.1
+     *
+     * @param {object} challenge Challenge object returned by API
+     * @returns {Promise<object>} Challenge
+     *
+     * @example Notify CA that challenge has been completed
+     * ```js
+     * const challenge = { ... }; // Satisfied challenge
+     * const result = await client.completeChallenge(challenge);
+     * ```
+     */
+    completeChallenge(challenge: any): Promise<any>;
+    /**
+     * Wait for ACME provider to verify status on a order, authorization or challenge
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.5.1
+     *
+     * @param {object} item An order, authorization or challenge object
+     * @returns {Promise<object>} Valid order, authorization or challenge
+     *
+     * @example Wait for valid challenge status
+     * ```js
+     * const challenge = { ... };
+     * await client.waitForValidStatus(challenge);
+     * ```
+     *
+     * @example Wait for valid authorization status
+     * ```js
+     * const authz = { ... };
+     * await client.waitForValidStatus(authz);
+     * ```
+     *
+     * @example Wait for valid order status
+     * ```js
+     * const order = { ... };
+     * await client.waitForValidStatus(order);
+     * ```
+     */
+    waitForValidStatus(item: any, d?: any): Promise<any>;
+    /**
+     * Get certificate from ACME order
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.4.2
+     *
+     * @param {object} order Order object
+     * @param {string} [preferredChain] Indicate which certificate chain is preferred if a CA offers multiple, by exact issuer common name, default: `null`
+     * @returns {Promise<string>} Certificate
+     *
+     * @example Get certificate
+     * ```js
+     * const order = { ... }; // Previously created order
+     * const certificate = await client.getCertificate(order);
+     * ```
+     *
+     * @example Get certificate with preferred chain
+     * ```js
+     * const order = { ... }; // Previously created order
+     * const certificate = await client.getCertificate(order, 'DST Root CA X3');
+     * ```
+     */
+    getCertificate(order: any, preferredChain?: any): Promise<any>;
+    /**
+     * Revoke certificate
+     *
+     * https://datatracker.ietf.org/doc/html/rfc8555#section-7.6
+     *
+     * @param {buffer|string} cert PEM encoded certificate
+     * @param {object} [data] Additional request data
+     * @returns {Promise}
+     *
+     * @example Revoke certificate
+     * ```js
+     * const certificate = { ... }; // Previously created certificate
+     * const result = await client.revokeCertificate(certificate);
+     * ```
+     *
+     * @example Revoke certificate with reason
+     * ```js
+     * const certificate = { ... }; // Previously created certificate
+     * const result = await client.revokeCertificate(certificate, {
+     *     reason: 4,
+     * });
+     * ```
+     */
+    revokeCertificate(cert: any, data?: {}): Promise<any>;
+    /**
+     * Auto mode
+     *
+     * @param {object} opts
+     * @param {buffer|string} opts.csr Certificate Signing Request
+     * @param {function} opts.challengeCreateFn Function returning Promise triggered before completing ACME challenge
+     * @param {function} opts.challengeRemoveFn Function returning Promise triggered after completing ACME challenge
+     * @param {string} [opts.email] Account email address
+     * @param {boolean} [opts.termsOfServiceAgreed] Agree to Terms of Service, default: `false`
+     * @param {boolean} [opts.skipChallengeVerification] Skip internal challenge verification before notifying ACME provider, default: `false`
+     * @param {string[]} [opts.challengePriority] Array defining challenge type priority, default: `['http-01', 'dns-01']`
+     * @param {string} [opts.preferredChain] Indicate which certificate chain is preferred if a CA offers multiple, by exact issuer common name, default: `null`
+     * @returns {Promise<string>} Certificate
+     *
+     * @example Order a certificate using auto mode
+     * ```js
+     * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
+     *     altNames: ['test.example.com'],
+     * });
+     *
+     * const certificate = await client.auto({
+     *     csr: certificateRequest,
+     *     email: 'test@example.com',
+     *     termsOfServiceAgreed: true,
+     *     challengeCreateFn: async (authz, challenge, keyAuthorization) => {
+     *         // Satisfy challenge here
+     *     },
+     *     challengeRemoveFn: async (authz, challenge, keyAuthorization) => {
+     *         // Clean up challenge here
+     *     },
+     * });
+     * ```
+     *
+     * @example Order a certificate using auto mode with preferred chain
+     * ```js
+     * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
+     *     altNames: ['test.example.com'],
+     * });
+     *
+     * const certificate = await client.auto({
+     *     csr: certificateRequest,
+     *     email: 'test@example.com',
+     *     termsOfServiceAgreed: true,
+     *     preferredChain: 'DST Root CA X3',
+     *     challengeCreateFn: async () => {},
+     *     challengeRemoveFn: async () => {},
+     * });
+     * ```
+     */
+    auto(opts: any): Promise<any>;
+}
+export default AcmeClient;