acmenamespacenamespace acmeAn 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
}acmenamespacenamespace acmeacme.LETS_ENCRYPTconstno test imports itconst LETS_ENCRYPT: "https://acme-v02.api.letsencrypt.org/directory"Let's Encrypt's production directory.
acme.LETS_ENCRYPT_STAGINGconstno test imports itconst 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 ittype 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 ittype KeyPair = { readonly publicKey: CryptoKey; readonly privateKey: CryptoKey };The two keys of an ECDSA key pair of Web Crypto.
acme.DnsProvidertypeno test imports ittype 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 ittype 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 ittype 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 itfunction pem(label: string, bytes: Uint8Array<ArrayBufferLike>): stringBytes as PEM: the label's lines around the base64, 64 characters a line.
acme.ecdsaRawToDerfunctionno test imports itfunction 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 itfunction 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 itfunction 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 itfunction challengeName(domain: string): stringThe name a DNS-01 TXT record is set at for a name (a wildcard's at its base name).
acme.csrfunctionno test imports itfunction 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 itfunction notAfterOf(certificatePem: string): Date | undefinedThe notAfter of the first certificate in PEM text, or undefined where there is none or it cannot be read.
acme.needsRenewalfunctionno test imports itfunction needsRenewal(certificatePem: string, now: Date, days?: number): booleanWhether 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 itfunction 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 itfunction 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; }): DnsProviderA DnsProvider over Cloudflare's API (v4) for one zone, by an API token allowed to edit its DNS (Zone.DNS).
LETS_ENCRYPTconstconst LETS_ENCRYPT: "https://acme-v02.api.letsencrypt.org/directory"Let's Encrypt's production directory.
LETS_ENCRYPT_STAGINGconstconst 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.
Jwktypeno test imports ittype 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 ittype KeyPair = { readonly publicKey: CryptoKey; readonly privateKey: CryptoKey };The two keys of an ECDSA key pair of Web Crypto.
DnsProvidertypetype 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.
IssueOptionstypeno test imports ittype 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 ittype 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.
pemfunctionfunction pem(label: string, bytes: Uint8Array<ArrayBufferLike>): stringBytes as PEM: the label's lines around the base64, 64 characters a line.
ecdsaRawToDerfunctionfunction 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.
jwkThumbprintfunctionfunction 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.
dns01Valuefunctionfunction 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).
challengeNamefunctionfunction challengeName(domain: string): stringThe name a DNS-01 TXT record is set at for a name (a wildcard's at its base name).
csrfunctionfunction 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.
notAfterOffunctionfunction notAfterOf(certificatePem: string): Date | undefinedThe notAfter of the first certificate in PEM text, or undefined where there is none or it cannot be read.
needsRenewalfunctionfunction needsRenewal(certificatePem: string, now: Date, days?: number): booleanWhether a certificate ends within days of now (or has ended, or cannot be read): the time to get a new one.
issuefunctionfunction 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).
cloudflareDnsfunctionfunction 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; }): DnsProviderA DnsProvider over Cloudflare's API (v4) for one zone, by an API token allowed to edit its DNS (Zone.DNS).