/**
* The ACME issuance flow shared by the `Certificate` resource (deploy time)
* and the `IssueCertificate` binding (runtime):
*
* order → DNS-01 per authorization (present → propagated → respond →
* poll) → finalize with a fresh key's CSR → download → parse.
*
* The wire is `@distilled.cloud/acme`; this file only sequences it.
*/
import * as Acme from "@distilled.cloud/acme";
import * as acme from "@distilled.cloud/acme/acme";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import type { CertificateAuthority } from "./CertificateAuthority.ts";
import { waitForTxt, type PropagationOptions } from "./Dns.ts";
import type { DnsChallengeRecord, DnsSolver } from "./DnsSolver.ts";
import {
ChallengeFailed,
ChallengeUnsupported,
OrderInvalid,
OrderTimeout,
PkiError,
type DnsPropagationTimeout,
type DnsSolverError,
} from "./Errors.ts";
import {
createCsr,
csrToBase64Url,
fromPem,
generateKey,
parseCertificate,
privateKeyToJwk,
splitPemChain,
type KeyAlgorithm,
type ParsedCertificate,
} from "./Pki.ts";
/** Everything the flow needs to sign requests as an account. */
export interface AccountCredentials {
readonly ca: CertificateAuthority;
/** The account's private JWK (JSON). */
readonly accountKey: Redacted.Redacted<string>;
/** The account URL (`kid`), once the account exists. */
readonly accountUrl?: string | undefined;
readonly externalAccountBinding?:
| { readonly keyId: string; readonly hmacKey: Redacted.Redacted<string> }
| undefined;
}
/**
* The SDK's `Credentials` (+ a CA-trusting `HttpClient` for private CAs)
* for one account. Provide around any `@distilled.cloud/acme` call.
*/
export const accountLayer = (
credentials: AccountCredentials,
): Layer.Layer<Acme.Credentials | HttpClient.HttpClient> => {
const creds = Acme.layer({
directoryUrl: credentials.ca.directoryUrl,
accountKey: credentials.accountKey,
accountUrl: credentials.accountUrl,
externalAccountBinding: credentials.externalAccountBinding,
});
const http =
credentials.ca.trustedRoot === undefined
? FetchHttpClient.layer
: FetchHttpClient.layer.pipe(
Layer.provideMerge(
Layer.succeed(FetchHttpClient.RequestInit, {
// Bun's fetch honours `tls`; the option is ignored elsewhere.
tls: { ca: credentials.ca.trustedRoot },
} as RequestInit),
),
);
return Layer.merge(creds, http);
};
export interface IssueRequest<R = never> {
/** DNS names; the first is the subject CN. Wildcards allowed. */
readonly identifiers: ReadonlyArray<string>;
readonly solver: DnsSolver<R>;
/** @default "ES256" */
readonly keyAlgorithm?: KeyAlgorithm | undefined;
/** Issuer name (`CN=...` substring) to prefer when the CA offers alternate chains. */
readonly preferredChain?: string | undefined;
readonly propagation?: PropagationOptions | undefined;
}
export interface IssuedCertificate {
/** Leaf certificate PEM. */
readonly certificate: string;
/** Full chain PEM, leaf first. */
readonly chain: string;
/** PKCS#8 private key PEM. */
readonly privateKey: Redacted.Redacted<string>;
readonly identifiers: ReadonlyArray<string>;
readonly serial: string;
/** ISO 8601. */
readonly notBefore: string;
/** ISO 8601. */
readonly notAfter: string;
readonly issuer: string;
/** The CA's certificate URL (for re-download and revocation bookkeeping). */
readonly certificateUrl: string;
readonly orderUrl: string;
}
export type IssueError =
| OrderInvalid
| ChallengeFailed
| ChallengeUnsupported
| OrderTimeout
| DnsPropagationTimeout
| DnsSolverError
| PkiError
| Acme.JoseError
| acme.NewOrderError
| acme.GetAuthorizationError
| acme.RespondChallengeError
| acme.FinalizeOrderError
| acme.GetOrderError
| acme.DownloadCertificateError;
const PENDING = new Set(["pending", "processing", "ready"]);
const challengeFqdn = (identifier: string): string =>
`_acme-challenge.${identifier.replace(/^\*\./, "")}`;
const problemsOf = (
order: acme.OrderResponse,
authorizations: ReadonlyArray<acme.Authorization>,
) => {
const problems: Array<{
identifier?: string;
type?: string;
detail?: string;
}> = [];
if (order.error) {
problems.push({ type: order.error.type, detail: order.error.detail });
}
for (const authorization of authorizations) {
for (const challenge of authorization.challenges) {
if (challenge.error) {
problems.push({
identifier: authorization.identifier.value,
type: challenge.error.type,
detail: challenge.error.detail,
});
}
}
}
return problems;
};
/**
* Complete one DNS-01 authorization and remove its TXT record on every exit.
*/
const solveAuthorization = <R>(
authorizationUrl: string,
jwk: Acme.Jose.Jwk,
solver: DnsSolver<R>,
propagation: PropagationOptions,
) =>
Effect.gen(function* () {
const authorization = yield* acme.getAuthorization({
url: authorizationUrl,
});
if (authorization.status === "valid") return authorization;
const identifier = authorization.identifier.value;
const challenge = authorization.challenges.find((c) => c.type === "dns-01");
if (challenge === undefined || challenge.token === undefined) {
return yield* new ChallengeUnsupported({
identifier,
offered: authorization.challenges.map((c) => c.type),
});
}
const record: DnsChallengeRecord = {
fqdn: challengeFqdn(identifier),
value: yield* Acme.Jose.dnsChallengeValue(challenge.token, jwk),
};
return yield* Effect.acquireUseRelease(
solver.present(record),
() =>
Effect.gen(function* () {
yield* solver.propagated === undefined
? waitForTxt(record.fqdn, record.value, propagation)
: solver.propagated(record, propagation);
yield* acme.respondChallenge({ url: challenge.url });
const settled = yield* acme.getAuthorization({ url: authorizationUrl }).pipe(
Effect.repeat({
schedule: Schedule.spaced("2 seconds"),
until: (a) => !PENDING.has(a.status),
times: 8,
}),
);
if (settled.status !== "valid") {
const failed = settled.challenges.find((c) => c.type === "dns-01");
return yield* new ChallengeFailed({
identifier,
type: failed?.error?.type,
detail: failed?.error?.detail ?? `authorization is ${settled.status}`,
});
}
return settled;
}),
() => solver.cleanup(record),
);
});
const chooseChain = (
downloaded: { chain: string; alternates?: ReadonlyArray<string> },
preferredChain: string | undefined,
) =>
Effect.gen(function* () {
const matches = (chain: string) =>
Effect.gen(function* () {
const blocks = splitPemChain(chain);
const top = blocks[blocks.length - 1];
if (top === undefined) return false;
const parsed = yield* parseCertificate(top).pipe(Effect.orElseSucceed(() => undefined));
return parsed?.issuer.includes(preferredChain!) === true;
});
if (preferredChain === undefined) return downloaded.chain;
if (yield* matches(downloaded.chain)) return downloaded.chain;
for (const url of downloaded.alternates ?? []) {
const alternate = yield* acme.downloadCertificate({ url });
if (yield* matches(alternate.chain)) return alternate.chain;
}
return downloaded.chain;
});
/**
* Issue a certificate for `identifiers` as the current `Credentials`
* account. Requires the SDK's `Credentials` and an `HttpClient` (see
* {@link accountLayer}) plus whatever the solver needs.
*/
export const issueCertificate = <R = never>(
request: IssueRequest<R>,
): Effect.Effect<IssuedCertificate, IssueError, Acme.Credentials | HttpClient.HttpClient | R> =>
Effect.gen(function* () {
const resolve = yield* Acme.Credentials;
const config = yield* resolve;
const jwk = yield* Acme.Jose.parseJwk(config.accountKey);
const propagation = request.propagation ?? {};
const order = yield* acme.newOrder({
identifiers: request.identifiers.map((value) => ({ type: "dns", value })),
});
if (order.location === undefined) {
return yield* new OrderInvalid({
orderUrl: order.finalize,
problems: [{ detail: "The CA omitted the order Location header." }],
});
}
const orderUrl = order.location;
// Each authorization removes its own TXT record on success or failure.
const authorizations = yield* Effect.forEach(
order.authorizations,
(url) => solveAuthorization(url, jwk, request.solver, propagation),
{ concurrency: 4 },
);
const ready = yield* acme.getOrder({ url: orderUrl }).pipe(
Effect.repeat({
schedule: Schedule.spaced("2 seconds"),
until: (value) => value.status !== "pending",
times: 8,
}),
);
if (ready.status === "invalid") {
return yield* new OrderInvalid({
orderUrl,
problems: problemsOf(ready, authorizations),
});
}
if (ready.status !== "ready") {
return yield* new OrderTimeout({ orderUrl, status: ready.status });
}
const key = yield* generateKey(request.keyAlgorithm ?? "ES256");
const csr = yield* createCsr({ key, identifiers: request.identifiers });
yield* acme.finalizeOrder({ url: order.finalize, csr: csrToBase64Url(csr) }).pipe(
Effect.retry({
while: (error) => error._tag === "AcmeOrderNotReady",
schedule: Schedule.spaced("1 second"),
times: 8,
}),
);
const settled = yield* acme.getOrder({ url: orderUrl }).pipe(
Effect.repeat({
schedule: Schedule.spaced("2 seconds"),
until: (o) => o.status === "valid" || o.status === "invalid",
times: 8,
}),
);
if (settled.status === "invalid") {
return yield* new OrderInvalid({
orderUrl,
problems: problemsOf(settled, authorizations),
});
}
if (settled.status !== "valid" || settled.certificate === undefined) {
return yield* new OrderTimeout({ orderUrl, status: settled.status });
}
const downloaded = yield* acme.downloadCertificate({
url: settled.certificate,
});
const chain = yield* chooseChain(downloaded, request.preferredChain);
const certificate = splitPemChain(chain)[0] ?? chain;
const parsed = yield* parseCertificate(certificate);
return toIssued({
certificate,
chain,
privateKey: key.privateKeyPem,
identifiers: request.identifiers,
certificateUrl: settled.certificate,
orderUrl,
parsed,
});
});
const toIssued = (input: {
certificate: string;
chain: string;
privateKey: Redacted.Redacted<string>;
identifiers: ReadonlyArray<string>;
certificateUrl: string;
orderUrl: string;
parsed: ParsedCertificate;
}): IssuedCertificate => ({
certificate: input.certificate,
chain: input.chain,
privateKey: input.privateKey,
identifiers: input.identifiers,
serial: input.parsed.serial,
notBefore: input.parsed.notBefore.toISOString(),
notAfter: input.parsed.notAfter.toISOString(),
issuer: input.parsed.issuer,
certificateUrl: input.certificateUrl,
orderUrl: input.orderUrl,
});
/** RFC 5280 revocation reasons. */
export type RevocationReason =
| "unspecified"
| "keyCompromise"
| "affiliationChanged"
| "superseded"
| "cessationOfOperation";
const REASON_CODES: Record<RevocationReason, number> = {
unspecified: 0,
keyCompromise: 1,
affiliationChanged: 3,
superseded: 4,
cessationOfOperation: 5,
};
export interface RevokeRequest {
/** Leaf certificate PEM. */
readonly certificate: string;
/**
* The certificate's private key. When given, the request is signed with
* it (RFC 8555 §7.6) so no account is needed; otherwise the ambient
* account credentials sign.
*/
readonly privateKey?: Redacted.Redacted<string> | string | undefined;
readonly reason?: RevocationReason | undefined;
}
export type RevokeError = PkiError | acme.RevokeCertificateError;
/** Revoke a certificate. `AcmeAlreadyRevoked` is folded into success. */
export const revokeCertificate = (
request: RevokeRequest,
): Effect.Effect<void, RevokeError, Acme.Credentials | HttpClient.HttpClient> =>
Effect.gen(function* () {
const leaf = splitPemChain(request.certificate)[0] ?? request.certificate;
const der = yield* Effect.try({
try: () => fromPem(leaf),
catch: (cause) => new PkiError({ message: "The certificate is not PEM.", cause }),
});
const revoke = acme
.revokeCertificate({
certificate: Acme.Jose.base64url(der),
reason: request.reason === undefined ? undefined : REASON_CODES[request.reason],
})
.pipe(Effect.catchTag("AcmeAlreadyRevoked", () => Effect.void));
if (request.privateKey === undefined) {
return yield* revoke;
}
// Sign with the certificate key (RFC 8555 §7.6): swap the account key
// and drop the account URL so the protocol embeds the JWK.
const resolve = yield* Acme.Credentials;
const config = yield* resolve;
const jwk = yield* privateKeyToJwk(request.privateKey);
return yield* revoke.pipe(
Effect.provide(Acme.layer({ directoryUrl: config.directoryUrl, accountKey: jwk })),
);
});