sailfork / t3code-github / .repos/ alchemy-effect/ packages/ acme/ src/ Certificate.ts

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,
          }),
        ),
      );
    }),
  });