@alchemy.run/acme 0.0.0-stage → 2.0.0-beta.84

package/src/Certificate.ts

@@ -0,0 +1,272 @@
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { arrayEqualsUnordered } from "alchemy/Util/equal";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { Account } from "./Account.ts";
+import {
+  accountLayer,
+  issueCertificate,
+  revokeCertificate,
+  type AccountCredentials,
+} from "./Client.ts";
+import type { PropagationOptions } from "./Dns.ts";
+import { resolveDnsSolver, type DnsSolverDescriptor } from "./DnsSolver.ts";
+import type { KeyAlgorithm } from "./Pki.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface CertificateProps {
+  /** The {@link Account} that orders the certificate. Changing it replaces. */
+  account: Account;
+  /**
+   * DNS names the certificate covers. The first is the subject CN;
+   * wildcards (`*.example.com`) are allowed. Changing the set re-issues.
+   */
+  identifiers: string[];
+  /**
+   * How `_acme-challenge` TXT records are published, e.g.
+   * `Cloudflare.ACME.ZoneSolver(zone)`. Changing the solver alone does not
+   * re-issue.
+   */
+  solver: DnsSolverDescriptor;
+  /**
+   * Certificate key algorithm. Changing it re-issues the certificate.
+   * @default "ES256"
+   */
+  keyAlgorithm?: KeyAlgorithm;
+  /**
+   * Re-issue when less than this remains before `notAfter`. Renewal is a
+   * `diff` result, so any `alchemy deploy` (a scheduled one, typically)
+   * renews.
+   * @default "30 days"
+   */
+  renewBefore?: Duration.Input;
+  /**
+   * Revoke the certificate at the CA when the resource is deleted. By
+   * default deletion only forgets the certificate.
+   * @default false
+   */
+  revokeOnDelete?: boolean;
+  /**
+   * Issuer name to prefer (`CN=…` substring, e.g. `ISRG Root X1`) when the
+   * CA offers alternate chains.
+   */
+  preferredChain?: string;
+  /** DNS propagation polling (resolvers, timeout, interval). */
+  propagation?: PropagationOptions;
+}
+
+export interface Certificate extends Resource<
+  "ACME.Certificate",
+  CertificateProps,
+  {
+    /** Leaf certificate PEM. */
+    certificate: string;
+    /** Full chain PEM, leaf first. */
+    chain: string;
+    /** PKCS#8 private key PEM. Sensitive; persisted in stack state. */
+    privateKey: Redacted.Redacted<string>;
+    /** Serial number, hex. */
+    serial: string;
+    /** ISO 8601 validity start. */
+    notBefore: string;
+    /** ISO 8601 expiry. Renewal is scheduled against it. */
+    notAfter: string;
+    /** Issuer distinguished name. */
+    issuer: string;
+    /** The DNS names covered. */
+    identifiers: string[];
+    /** The CA's certificate URL. */
+    certificateUrl: string;
+    /** The CA's order URL. */
+    orderUrl: string;
+    /** Key algorithm of `privateKey`. */
+    keyAlgorithm: KeyAlgorithm;
+    /** The account that issued the certificate. */
+    accountUrl: string;
+    /** The CA the certificate was issued by (for revocation on delete). */
+    directoryUrl: string;
+    /** PEM root trusted for the CA's endpoint (private CAs only). */
+    trustedRoot: string | undefined;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A TLS certificate issued over ACME at deploy time, with renewal.
+ *
+ * Reconcile places an order, proves control of every name over DNS-01
+ * through the `solver`, finalizes with a fresh key's CSR and stores the
+ * chain and redacted private key in state. Protect the state store as
+ * secret material. `diff` reports an update when the
+ * names change or when `renewBefore` of validity remains, so a scheduled
+ * `alchemy deploy` keeps certificates fresh.
+ *
+ * ### Wildcard certificate
+ * **Example:** Let's Encrypt wildcard over Cloudflare DNS
+ * ```typescript
+ * const account = yield* ACME.Account("Issuer", {
+ *   ca: ACME.LetsEncrypt,
+ *   termsOfServiceAgreed: true,
+ * });
+ * const zone = yield* Zone;
+ * const wildcard = yield* ACME.Certificate("Wildcard", {
+ *   account,
+ *   identifiers: ["*.example.com", "example.com"],
+ *   solver: Cloudflare.ACME.ZoneSolver(zone),
+ * });
+ * ```
+ *
+ * ### Using the certificate
+ * The chain and key are Outputs — pass them to whatever terminates TLS.
+ *
+ * **Example:** Upload to a Fly App
+ * ```typescript
+ * const www = yield* Fly.Certificate("Www", {
+ *   app: Site,
+ *   hostname: "www.example.com",
+ *   kind: "custom",
+ *   fullchain: wildcard.chain,
+ *   privateKey: wildcard.privateKey,
+ * });
+ * ```
+ *
+ * ### Renewal
+ * **Example:** Renew earlier and revoke on delete
+ * ```typescript
+ * const api = yield* ACME.Certificate("Api", {
+ *   account,
+ *   identifiers: ["api.example.com"],
+ *   solver: Cloudflare.ACME.ZoneSolver(zone),
+ *   renewBefore: "45 days",
+ *   revokeOnDelete: true,
+ * });
+ * ```
+ *
+ * @resource
+ * @product Certificate
+ * @category Certificates
+ */
+export const Certificate = Resource<Certificate>("ACME.Certificate");
+
+type AccountRef = {
+  directoryUrl: string;
+  trustedRoot?: string | undefined;
+  accountUrl: string;
+  privateKey: Redacted.Redacted<string>;
+};
+
+/** The resolved account attributes behind a resource-valued prop. */
+const accountOf = (value: unknown): AccountRef => value as AccountRef;
+
+const credentialsOf = (account: AccountRef): AccountCredentials => ({
+  ca: { directoryUrl: account.directoryUrl, trustedRoot: account.trustedRoot },
+  accountKey: account.privateKey,
+  accountUrl: account.accountUrl,
+});
+
+const DEFAULT_RENEW_BEFORE: Duration.Input = "30 days";
+
+const renewalDue = (
+  notAfter: string,
+  renewBefore: Duration.Input | undefined,
+  now: number,
+): boolean => Date.parse(notAfter) - now < Duration.toMillis(renewBefore ?? DEFAULT_RENEW_BEFORE);
+
+export const CertificateProvider = () =>
+  Provider.succeed(Certificate, {
+    stables: ["directoryUrl"],
+
+    diff: Effect.fn(function* ({ news, olds, output }) {
+      if (news === undefined || !isResolved(news) || output === undefined) {
+        return undefined;
+      }
+      const account = accountOf(news.account);
+      if (account.accountUrl !== output.accountUrl) {
+        return { action: "replace" as const };
+      }
+      const now = yield* Effect.sync(() => Date.now());
+      const reissue =
+        !arrayEqualsUnordered(news.identifiers, output.identifiers) ||
+        (news.keyAlgorithm ?? "ES256") !== output.keyAlgorithm ||
+        news.preferredChain !== olds?.preferredChain ||
+        renewalDue(output.notAfter, news.renewBefore, now);
+      return reissue ? { action: "update" as const } : undefined;
+    }),
+
+    read: Effect.fn(function* ({ output }) {
+      return output;
+    }),
+
+    reconcile: Effect.fn(function* ({ news, olds, output }) {
+      const account = accountOf(news.account);
+      const keyAlgorithm = news.keyAlgorithm ?? "ES256";
+      const now = yield* Effect.sync(() => Date.now());
+      // Observe: the stored certificate is authoritative — nothing to do
+      // while it covers the names and isn't due.
+      if (
+        output !== undefined &&
+        output.accountUrl === account.accountUrl &&
+        arrayEqualsUnordered(news.identifiers, output.identifiers) &&
+        output.keyAlgorithm === keyAlgorithm &&
+        news.preferredChain === olds?.preferredChain &&
+        !renewalDue(output.notAfter, news.renewBefore, now)
+      ) {
+        return {
+          ...output,
+          directoryUrl: account.directoryUrl,
+          trustedRoot: account.trustedRoot,
+        };
+      }
+      const solver = yield* resolveDnsSolver(news.solver);
+      const issued = yield* issueCertificate({
+        identifiers: news.identifiers,
+        solver,
+        keyAlgorithm,
+        preferredChain: news.preferredChain,
+        propagation: news.propagation,
+      }).pipe(Effect.provide(accountLayer(credentialsOf(account))));
+      return {
+        certificate: issued.certificate,
+        chain: issued.chain,
+        privateKey: issued.privateKey,
+        serial: issued.serial,
+        notBefore: issued.notBefore,
+        notAfter: issued.notAfter,
+        issuer: issued.issuer,
+        identifiers: [...news.identifiers],
+        certificateUrl: issued.certificateUrl,
+        orderUrl: issued.orderUrl,
+        keyAlgorithm,
+        accountUrl: account.accountUrl,
+        directoryUrl: account.directoryUrl,
+        trustedRoot: account.trustedRoot,
+      };
+    }),
+
+    delete: Effect.fn(function* ({ olds, output }) {
+      if (olds.revokeOnDelete !== true) return;
+      const account = accountOf(olds.account);
+      // Signed with the certificate's own key, so revocation works even
+      // after the account was replaced or deactivated.
+      yield* revokeCertificate({
+        certificate: output.certificate,
+        privateKey: output.privateKey,
+        reason: "cessationOfOperation",
+      }).pipe(
+        Effect.provide(
+          accountLayer({
+            ca: {
+              directoryUrl: output.directoryUrl,
+              trustedRoot: output.trustedRoot,
+            },
+            accountKey: account.privateKey,
+            accountUrl: account.accountUrl,
+          }),
+        ),
+      );
+    }),
+  });

package/src/CertificateAuthority.ts

@@ -0,0 +1,41 @@
+import { Directories } from "@distilled.cloud/acme";
+
+/**
+ * An ACME certificate authority: its directory URL plus, for private CAs
+ * (Pebble, step-ca), the PEM root that signs the CA's own HTTPS endpoint.
+ */
+export interface CertificateAuthority {
+  /** The CA's ACME directory URL. */
+  readonly directoryUrl: string;
+  /**
+   * PEM root certificate to trust for the CA's HTTPS endpoint. Only for
+   * private CAs whose API certificate is not publicly trusted; public CAs
+   * leave it unset.
+   */
+  readonly trustedRoot?: string | undefined;
+}
+
+/** Let's Encrypt production. No External Account Binding. */
+export const LetsEncrypt: CertificateAuthority = {
+  directoryUrl: Directories.LetsEncrypt,
+};
+
+/** Let's Encrypt staging: generous limits, untrusted chain. */
+export const LetsEncryptStaging: CertificateAuthority = {
+  directoryUrl: Directories.LetsEncryptStaging,
+};
+
+/** ZeroSSL. Requires an External Account Binding (`eab`). */
+export const ZeroSSL: CertificateAuthority = {
+  directoryUrl: Directories.ZeroSSL,
+};
+
+/** Google Trust Services. Requires an External Account Binding (`eab`). */
+export const GoogleTrustServices: CertificateAuthority = {
+  directoryUrl: Directories.GoogleTrustServices,
+};
+
+/** Google Trust Services staging. */
+export const GoogleTrustServicesStaging: CertificateAuthority = {
+  directoryUrl: Directories.GoogleTrustServicesStaging,
+};