IF Commons GitHub

acme

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-net FR-008

An ACME client (RFC 8555) that gets a certificate by the DNS-01 challenge (commons 0013-acme): an account (made, or found again by its key with onlyReturnExisting), an order for the names, a TXT record _acme-challenge.<name> holding the base64url SHA-256 of each key authorization, the challenges answered, the authorizations and the order polled with a growing wait (or the server's Retry-After), a certificate signing request for a new ES256 key with the names as its subject alternative names (built with the kernel's der), the order finalized and the certificate downloaded. Every request is a JWS (ES256: the account's JWK until the account exists, its kid after) with a fresh nonce, and a badNonce refusal is retried with the nonce it carries. The TXT records set are always removed, whether the certificate came or not. cloudflareDns is a DnsProvider over Cloudflare's API; needsRenewal and notAfterOf read a certificate's validity.

Every expected failure (the server refuses, a challenge is invalid, the DNS provider throws, the network fails, the wait runs out) is a Result with one sentence; nothing secret (the token, a private key) is ever in it.

import { cloudflareDns, issue, LETS_ENCRYPT_STAGING } from "./acme.ts";
const r = await issue({
  directory: LETS_ENCRYPT_STAGING,
  domains: ["erga.fyi", "*.erga.fyi"],
  dns: cloudflareDns({ token: "<a token with Zone.DNS edit>", zone: "erga.fyi" }),
  contact: ["mailto:ops@example.com"],
});
if (r.kind === "ok") {
  // keep r.value.accountKey for the next renewal; write r.value.certificatePem and r.value.privateKeyPem where the server reads them
}

Source: commons/net/src/acme.ts

13 of 34 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

acmenamespace
namespace acme
acme.LETS_ENCRYPTconstno test imports it
const LETS_ENCRYPT: "https://acme-v02.api.letsencrypt.org/directory"

Let's Encrypt's production directory.

acme.LETS_ENCRYPT_STAGINGconstno test imports it
const LETS_ENCRYPT_STAGING: "https://acme-staging-v02.api.letsencrypt.org/directory"

Let's Encrypt's staging directory: certificates no browser trusts, for trying a setup without its rate limits.

acme.Jwktypeno test imports it
type Jwk = {
  readonly alg?: string;
  readonly crv?: string;
  readonly d?: string;
  readonly e?: string;
  readonly ext?: boolean;
  readonly key_ops?: string[];
  readonly kty?: string;
  readonly n?: string;
  readonly use?: string;
  readonly x?: string;
  readonly y?: string;
};

A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.

acme.KeyPairtypeno test imports it
type KeyPair = { readonly publicKey: CryptoKey; readonly privateKey: CryptoKey };

The two keys of an ECDSA key pair of Web Crypto.

acme.DnsProvidertypeno test imports it
type DnsProvider = {
  setTxt(name: string, value: string): Promise<void>;
  removeTxt(name: string, value: string): Promise<void>;
};

Where TXT records are set and removed (a zone's DNS host): name is the whole name, value the record's text.

acme.IssueOptionstypeno test imports it
type IssueOptions = { /** The ACME directory's URL (`LETS_ENCRYPT`, `LETS_ENCRYPT_STAGING`, or another CA's). */ rea… (1169 characters)
type IssueOptions = {
  /** The ACME directory's URL (`LETS_ENCRYPT`, `LETS_ENCRYPT_STAGING`, or another CA's). */
  readonly directory: string;
  /** The names the certificate is for; the first is also its common name. A wildcard (`*.erga.fyi`) is proven at `_acme-challenge.erga.fyi`. */
  readonly domains: readonly string[];
  readonly dns: DnsProvider;
  /** The account's ES256 private key as a JWK; a new one is made where it is absent (and given back to keep). */
  readonly accountKey?: Jwk;
  /** The account's contacts (`mailto:...`), sent when the account is made. */
  readonly contact?: readonly string[];
  /** Called for each TXT record once all are set, before the challenges are answered: wait until the record can be seen. */
  readonly propagationWait?: (name: string, value: string) => Promise<void>;
  /** The `fetch` used (a stub, in tests). */
  readonly fetch?: typeof fetch;
  /** The first wait between two polls, growing by half each time up to ten times this (1000 by default). */
  readonly pollIntervalMs?: number;
  /** How long an authorization or the order may take, in all (300000 by default). */
  readonly pollTimeoutMs?: number;
};

What issue takes.

acme.Issuedtypeno test imports it
type Issued = { /** The certificate and its chain, PEM, as the CA gives them. */ readonly certificatePem: string; … (557 characters)
type Issued = {
  /** The certificate and its chain, PEM, as the CA gives them. */
  readonly certificatePem: string;
  /** The certificate's ES256 private key, PKCS #8 PEM. */
  readonly privateKeyPem: string;
  /** The account's ES256 private key as a JWK: keep it (it is a secret) and give it to the next `issue`. */
  readonly accountKey: Jwk;
  /** The certificate's `notAfter`, ISO 8601. */
  readonly notAfter: string;
  /** A TXT record that could not be removed, one sentence each (none when all were). */
  readonly warnings: readonly string[];
};

What issue gives: the certificate chain, its key, the account's key to keep, the end of its validity, and what could not be cleaned up.

acme.pemfunctionno test imports it
function pem(label: string, bytes: Uint8Array<ArrayBufferLike>): string

Bytes as PEM: the label's lines around the base64, 64 characters a line.

acme.ecdsaRawToDerfunctionno test imports it
function ecdsaRawToDer(raw: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBufferLike>

An ECDSA P-256 signature as raw r || s (what Web Crypto gives) turned into DER (SEQUENCE { r INTEGER, s INTEGER }), as X.509 wants it.

acme.jwkThumbprintfunctionno test imports it
function jwkThumbprint(jwk: Jwk): Promise<string>

The RFC 7638 thumbprint of an EC public JWK: the base64url SHA-256 of {"crv","kty","x","y"} in that order.

acme.dns01Valuefunctionno test imports it
function dns01Value(token: string, thumbprint: string): Promise<string>

The TXT value of a DNS-01 challenge: the base64url SHA-256 of the key authorization token.thumbprint (RFC 8555 §8.4).

acme.challengeNamefunctionno test imports it
function challengeName(domain: string): string

The name a DNS-01 TXT record is set at for a name (a wildcard's at its base name).

acme.csrfunctionno test imports it
function csr(domains: readonly string[], keys: KeyPair): Promise<Uint8Array<ArrayBufferLike>>

A certification request (PKCS #10, RFC 2986) for these names, signed by the key: the first name as the common name, all as DNS SANs.

acme.notAfterOffunctionno test imports it
function notAfterOf(certificatePem: string): Date | undefined

The notAfter of the first certificate in PEM text, or undefined where there is none or it cannot be read.

acme.needsRenewalfunctionno test imports it
function needsRenewal(certificatePem: string, now: Date, days?: number): boolean

Whether a certificate ends within days of now (or has ended, or cannot be read): the time to get a new one.

acme.issuefunctionno test imports it
function issue(o: IssueOptions): Promise<Result<Issued, string>>

A certificate for domains from the ACME server at directory, proven by DNS-01 through dns; or why not. The TXT records set are removed in every case; one that could not be removed is a warning of the result (or added to its error).

acme.cloudflareDnsfunctionno test imports it
function cloudflareDns(o: { readonly token: string; readonly zone: string; readonly api?: string | undefined; readonly fetch?: { (input: URL | RequestInfo, init?: RequestInit | undefined): Promise<Response>; (input: string | Request | URL, init?: RequestInit | undefined): Promise<Response>; } | undefined; }): DnsProvider

A DnsProvider over Cloudflare's API (v4) for one zone, by an API token allowed to edit its DNS (Zone.DNS).

LETS_ENCRYPTconst
const LETS_ENCRYPT: "https://acme-v02.api.letsencrypt.org/directory"

Let's Encrypt's production directory.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

LETS_ENCRYPT_STAGINGconst
const LETS_ENCRYPT_STAGING: "https://acme-staging-v02.api.letsencrypt.org/directory"

Let's Encrypt's staging directory: certificates no browser trusts, for trying a setup without its rate limits.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

Jwktypeno test imports it
type Jwk = {
  readonly alg?: string;
  readonly crv?: string;
  readonly d?: string;
  readonly e?: string;
  readonly ext?: boolean;
  readonly key_ops?: string[];
  readonly kty?: string;
  readonly n?: string;
  readonly use?: string;
  readonly x?: string;
  readonly y?: string;
};

A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.

KeyPairtypeno test imports it
type KeyPair = { readonly publicKey: CryptoKey; readonly privateKey: CryptoKey };

The two keys of an ECDSA key pair of Web Crypto.

DnsProvidertype
type DnsProvider = {
  setTxt(name: string, value: string): Promise<void>;
  removeTxt(name: string, value: string): Promise<void>;
};

Where TXT records are set and removed (a zone's DNS host): name is the whole name, value the record's text.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

IssueOptionstypeno test imports it
type IssueOptions = { /** The ACME directory's URL (`LETS_ENCRYPT`, `LETS_ENCRYPT_STAGING`, or another CA's). */ rea… (1169 characters)
type IssueOptions = {
  /** The ACME directory's URL (`LETS_ENCRYPT`, `LETS_ENCRYPT_STAGING`, or another CA's). */
  readonly directory: string;
  /** The names the certificate is for; the first is also its common name. A wildcard (`*.erga.fyi`) is proven at `_acme-challenge.erga.fyi`. */
  readonly domains: readonly string[];
  readonly dns: DnsProvider;
  /** The account's ES256 private key as a JWK; a new one is made where it is absent (and given back to keep). */
  readonly accountKey?: Jwk;
  /** The account's contacts (`mailto:...`), sent when the account is made. */
  readonly contact?: readonly string[];
  /** Called for each TXT record once all are set, before the challenges are answered: wait until the record can be seen. */
  readonly propagationWait?: (name: string, value: string) => Promise<void>;
  /** The `fetch` used (a stub, in tests). */
  readonly fetch?: typeof fetch;
  /** The first wait between two polls, growing by half each time up to ten times this (1000 by default). */
  readonly pollIntervalMs?: number;
  /** How long an authorization or the order may take, in all (300000 by default). */
  readonly pollTimeoutMs?: number;
};

What issue takes.

Issuedtypeno test imports it
type Issued = { /** The certificate and its chain, PEM, as the CA gives them. */ readonly certificatePem: string; … (557 characters)
type Issued = {
  /** The certificate and its chain, PEM, as the CA gives them. */
  readonly certificatePem: string;
  /** The certificate's ES256 private key, PKCS #8 PEM. */
  readonly privateKeyPem: string;
  /** The account's ES256 private key as a JWK: keep it (it is a secret) and give it to the next `issue`. */
  readonly accountKey: Jwk;
  /** The certificate's `notAfter`, ISO 8601. */
  readonly notAfter: string;
  /** A TXT record that could not be removed, one sentence each (none when all were). */
  readonly warnings: readonly string[];
};

What issue gives: the certificate chain, its key, the account's key to keep, the end of its validity, and what could not be cleaned up.

pemfunction
function pem(label: string, bytes: Uint8Array<ArrayBufferLike>): string

Bytes as PEM: the label's lines around the base64, 64 characters a line.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

ecdsaRawToDerfunction
function ecdsaRawToDer(raw: Uint8Array<ArrayBufferLike>): Uint8Array<ArrayBufferLike>

An ECDSA P-256 signature as raw r || s (what Web Crypto gives) turned into DER (SEQUENCE { r INTEGER, s INTEGER }), as X.509 wants it.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

jwkThumbprintfunction
function jwkThumbprint(jwk: Jwk): Promise<string>

The RFC 7638 thumbprint of an EC public JWK: the base64url SHA-256 of {"crv","kty","x","y"} in that order.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

dns01Valuefunction
function dns01Value(token: string, thumbprint: string): Promise<string>

The TXT value of a DNS-01 challenge: the base64url SHA-256 of the key authorization token.thumbprint (RFC 8555 §8.4).

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

challengeNamefunction
function challengeName(domain: string): string

The name a DNS-01 TXT record is set at for a name (a wildcard's at its base name).

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

csrfunction
function csr(domains: readonly string[], keys: KeyPair): Promise<Uint8Array<ArrayBufferLike>>

A certification request (PKCS #10, RFC 2986) for these names, signed by the key: the first name as the common name, all as DNS SANs.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

notAfterOffunction
function notAfterOf(certificatePem: string): Date | undefined

The notAfter of the first certificate in PEM text, or undefined where there is none or it cannot be read.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

needsRenewalfunction
function needsRenewal(certificatePem: string, now: Date, days?: number): boolean

Whether a certificate ends within days of now (or has ended, or cannot be read): the time to get a new one.

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

issuefunction
function issue(o: IssueOptions): Promise<Result<Issued, string>>

A certificate for domains from the ACME server at directory, proven by DNS-01 through dns; or why not. The TXT records set are removed in every case; one that could not be removed is a warning of the result (or added to its error).

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

cloudflareDnsfunction
function cloudflareDns(o: { readonly token: string; readonly zone: string; readonly api?: string | undefined; readonly fetch?: { (input: URL | RequestInfo, init?: RequestInit | undefined): Promise<Response>; (input: string | Request | URL, init?: RequestInit | undefined): Promise<Response>; } | undefined; }): DnsProvider

A DnsProvider over Cloudflare's API (v4) for one zone, by an API token allowed to edit its DNS (Zone.DNS).

Imported by 10 tests of the run (10 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.