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

import type {
  CertificateCheckResponse,
  CertificateDetail,
  CertificateSummary,
  CertificateValidation as FlyCertificateValidation,
  DNSRequirements,
} from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import { listOwnedApps } from "./App.ts";
import type { App } from "./App.ts";
import type { Providers } from "./Providers.ts";

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* App(...)` and `App(...)` both type-check).
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

export type CertificateKind = "acme" | "custom";

export type CertificateSource = "custom" | "fly";

export type CertificateDnsRequirements = {
  a?: string[];
  aaaa?: string[];
  acmeChallenge?: { name?: string; target?: string };
  cname?: string;
  ownership?: { appValue?: string; name?: string; orgValue?: string };
};

export type CertificateValidationState = {
  alpnConfigured?: boolean;
  dnsConfigured?: boolean;
  httpConfigured?: boolean;
  ownershipTxtConfigured?: boolean;
};

export interface CertificateProps {
  /**
   * Parent Fly App. Accepts a `Fly.App` resource or an Effect that
   * produces one. Changing the App replaces the Certificate.
   */
  app: Ref<App>;
  /**
   * Hostname this Certificate covers. Identity of the resource.
   * Changing it replaces the Certificate.
   */
  hostname: string;
  /**
   * How the Certificate is issued. `"acme"` requests a Let's Encrypt
   * certificate (`createAppAcmeCertificate`). `"custom"` uploads a PEM
   * (`createAppCustomCertificate`). Changing kind replaces.
   *
   * @default "acme"
   */
  kind?: CertificateKind;
  /**
   * PEM-encoded certificate chain. Required when `kind` is `"custom"`.
   * Updating it re-uploads in place (custom create upsert, or
   * delete+create if the API conflicts).
   */
  fullchain?: string;
  /**
   * PEM-encoded private key. Required when `kind` is `"custom"`. Wrap
   * with `Redacted.make` to keep it out of logs. Never stored in
   * attributes.
   */
  privateKey?: Redacted.Redacted<string> | string;
}

export type Certificate = Resource<
  "Fly.Certificate",
  CertificateProps,
  {
    /** Physical Fly App name the Certificate is attached to. */
    appName: string;
    /** Hostname this Certificate covers. Identity of the resource. */
    hostname: string;
    /** Observed status (`active`, `pending_validation`, …). */
    status: string | undefined;
    /** Whether DNS/ownership validation has completed. */
    configured: boolean | undefined;
    /** Whether ACME issuance has been requested for this hostname. */
    acmeRequested: boolean | undefined;
    /** DNS records Fly expects for validation. */
    dnsRequirements: CertificateDnsRequirements | undefined;
    /** Per-challenge validation flags. */
    validation: CertificateValidationState | undefined;
    /** Observed source: `"custom"` for uploaded PEMs, `"fly"` for ACME. */
    source: CertificateSource;
  },
  never,
  Providers
>;

/**
 * A Fly.Certificate covers a hostname on an {@link App}. Default
 * `kind` is `"acme"` (Let's Encrypt). `"custom"` uploads a PEM.
 *
 * IPs and certificates attach to the App. A {@link Service} publishes
 * ports. Fly's proxy terminates TLS on 443 once the certificate is
 * `configured`.
 *
 * @see https://fly.io/docs/machines/api/certificates-resource/
 *
 * ### ACME certificates
 * Request Let's Encrypt for a hostname. The Service does not change.
 * Yield the certificate in the Stack. Point DNS at the App.
 *
 * **Example:** Let's Encrypt
 * ```typescript
 * export const Www = Fly.Certificate("Www", {
 *   app: Site,
 *   hostname: "www.example.com",
 * });
 * ```
 *
 * :::caution[Changing `hostname` replaces the Certificate]
 * Hostname is the identity. The old hostname is deleted, then the new
 * one is created.
 * :::
 *
 * :::caution[Changing `app` or `kind` replaces the Certificate]
 * The certificate is created on the new App or with the new issuer.
 * :::
 *
 * ### DNS
 * Point an A record at a `shared_v4` {@link IpAssignment} and an AAAA
 * at `v6`. Plus whatever `dnsRequirements` lists for the ACME
 * challenge. Alchemy re-checks via `checkAppCertificate` while
 * `configured` is false.
 *
 * Observed attrs include `status`, `configured`, `acmeRequested`,
 * `dnsRequirements`, and `validation`.
 *
 * **Example:** Yield next to a Service
 * ```typescript
 * export default Alchemy.Stack(
 *   "MyApp",
 *   { providers: Fly.providers(), state: Alchemy.localState() },
 *   Effect.gen(function* () {
 *     const api = yield* Api;
 *     const ip = yield* PublicIp;
 *     const v6 = yield* V6;
 *     const www = yield* Www;
 *     return {
 *       url: api.url,
 *       ip: ip.ip,
 *       v6: v6.ip,
 *       dns: www.dnsRequirements,
 *     };
 *   }),
 * );
 * ```
 *
 * ### Custom certificates
 * `"custom"` uploads `fullchain` and `privateKey`. Wrap the key with
 * `Redacted.make` so it never logs. Never stored in attributes.
 * Updating the PEM re-uploads in place.
 *
 * **Example:** Upload a PEM
 * ```typescript
 * export const Www = Fly.Certificate("Www", {
 *   app: Site,
 *   hostname: "www.example.com",
 *   kind: "custom",
 *   fullchain: pem,
 *   privateKey: Redacted.make(key),
 * });
 * ```
 *
 * @resource
 * @product Certificate
 */
export const Certificate = Resource<Certificate>("Fly.Certificate");

export class CertificateNotCreated extends Data.TaggedError("Fly.CertificateNotCreated")<{
  appName: string;
  hostname: string;
}> {}

export class CertificateAppMissing extends Data.TaggedError("Fly.CertificateAppMissing")<{
  hostname: string;
}> {}

export class CertificateMaterialRequired extends Data.TaggedError(
  "Fly.CertificateMaterialRequired",
)<{
  hostname: string;
}> {}

type ObservedCert = CertificateDetail | CertificateCheckResponse;

const appNameOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { appName?: unknown; name?: unknown };
  if (typeof rec.appName === "string" && rec.appName.length > 0) {
    return rec.appName;
  }
  if (typeof rec.name === "string" && rec.name.length > 0) {
    return rec.name;
  }
  return undefined;
};

const unwrapSecret = (
  value: Redacted.Redacted<string> | string | undefined,
): string | undefined => {
  if (value === undefined) return undefined;
  return Redacted.isRedacted(value) ? Redacted.value(value) : value;
};

const normalizePem = (pem: string | undefined): string => (pem ?? "").replace(/\r\n/g, "\n").trim();

const desiredKind = (props: Pick<CertificateProps, "kind">): CertificateKind =>
  props.kind ?? "acme";

const kindOf = (source: CertificateSource): CertificateKind =>
  source === "custom" ? "custom" : "acme";

const sourceOf = (detail: ObservedCert): CertificateSource => {
  const entries = detail.certificates ?? [];
  if (entries.some((entry) => entry.source === "custom")) return "custom";
  if (entries.some((entry) => entry.source === "fly")) return "fly";
  return detail.acme_requested === true ? "fly" : "custom";
};

const sourceFromSummary = (summary: CertificateSummary): CertificateSource =>
  summary.has_custom_certificate === true ? "custom" : "fly";

const toDnsRequirements = (
  req: DNSRequirements | undefined,
): CertificateDnsRequirements | undefined => {
  if (req === undefined) return undefined;
  return {
    a: req.a,
    aaaa: req.aaaa,
    acmeChallenge:
      req.acme_challenge === undefined
        ? undefined
        : {
            name: req.acme_challenge.name,
            target: req.acme_challenge.target,
          },
    cname: req.cname,
    ownership:
      req.ownership === undefined
        ? undefined
        : {
            appValue: req.ownership.app_value,
            name: req.ownership.name,
            orgValue: req.ownership.org_value,
          },
  };
};

const toValidation = (
  validation: FlyCertificateValidation | undefined,
): CertificateValidationState | undefined => {
  if (validation === undefined) return undefined;
  return {
    alpnConfigured: validation.alpn_configured,
    dnsConfigured: validation.dns_configured,
    httpConfigured: validation.http_configured,
    ownershipTxtConfigured: validation.ownership_txt_configured,
  };
};

const toAttrs = (
  appName: string,
  detail: ObservedCert,
  fallbackHostname?: string,
): Certificate["Attributes"] => ({
  appName,
  hostname: detail.hostname ?? fallbackHostname ?? "",
  status: detail.status,
  configured: detail.configured,
  acmeRequested: detail.acme_requested,
  dnsRequirements: toDnsRequirements(detail.dns_requirements),
  validation: toValidation(detail.validation),
  source: sourceOf(detail),
});

const toAttrsFromSummary = (
  appName: string,
  summary: CertificateSummary,
): Certificate["Attributes"] | undefined => {
  const hostname = summary.hostname;
  if (hostname === undefined || hostname.length === 0) return undefined;
  return {
    appName,
    hostname,
    status: summary.status,
    configured: summary.configured,
    acmeRequested: summary.acme_requested,
    dnsRequirements: undefined,
    validation: {
      alpnConfigured: summary.acme_alpn_configured,
      dnsConfigured: summary.acme_dns_configured,
      httpConfigured: summary.acme_http_configured,
      ownershipTxtConfigured: summary.ownership_txt_configured,
    },
    source: sourceFromSummary(summary),
  };
};

const getByHostname = (appName: string, hostname: string) =>
  machines
    .getAppCertificate({ app_name: appName, hostname })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listAppCertificates = (appName: string) =>
  Effect.gen(function* () {
    const all: CertificateSummary[] = [];
    let cursor: string | undefined;
    for (let i = 0; i < 8; i++) {
      const page = yield* machines
        .listAppCertificates({
          app_name: appName,
          cursor,
          limit: 100,
        })
        .pipe(
          Effect.catchTag(["NotFound", "Forbidden"], () =>
            Effect.succeed({
              certificates: [] as CertificateSummary[],
              next_cursor: undefined,
            }),
          ),
        );
      all.push(...(page.certificates ?? []));
      if (page.next_cursor === undefined || page.next_cursor.length === 0) {
        break;
      }
      cursor = page.next_cursor;
    }
    return all;
  });

const waitUntilGone = (appName: string, hostname: string) =>
  getByHostname(appName, hostname).pipe(
    Effect.map((found) => found === undefined),
    Effect.repeat({
      schedule: Schedule.spaced("1 second"),
      until: (gone) => gone,
      times: 8,
    }),
  );

const requireCustomMaterial = (
  hostname: string,
  fullchain: string | undefined,
  privateKey: string | undefined,
) =>
  fullchain === undefined ||
  fullchain.length === 0 ||
  privateKey === undefined ||
  privateKey.length === 0
    ? new CertificateMaterialRequired({ hostname })
    : undefined;

const createAcme = (appName: string, hostname: string) =>
  machines
    .createAppAcmeCertificate({
      app_name: appName,
      hostname,
    })
    .pipe(Effect.catchTag("Conflict", () => Effect.undefined));

const createCustom = (appName: string, hostname: string, fullchain: string, privateKey: string) =>
  machines
    .createAppCustomCertificate({
      app_name: appName,
      hostname,
      fullchain,
      private_key: privateKey,
    })
    .pipe(Effect.catchTag("Conflict", () => Effect.undefined));

const replaceCustom = (appName: string, hostname: string, fullchain: string, privateKey: string) =>
  Effect.gen(function* () {
    yield* machines
      .deleteAppCustomCertificate({
        app_name: appName,
        hostname,
      })
      .pipe(Effect.catchTag("NotFound", () => Effect.void));
    yield* machines.createAppCustomCertificate({
      app_name: appName,
      hostname,
      fullchain,
      private_key: privateKey,
    });
  });

export const CertificateProvider = () =>
  Provider.succeed(Certificate, {
    stables: ["appName", "hostname", "source"],
    nuke: { dependsOn: ["Fly.App"] },

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const appName = appNameOf(news.app);
      const appChanged = appName !== undefined && appName !== output.appName;
      const hostnameChanged = news.hostname !== output.hostname;
      const nextKind = desiredKind(news);
      const kindChanged = nextKind !== kindOf(output.source);
      if (appChanged || hostnameChanged || kindChanged) {
        return {
          action: "replace" as const,
          // Same hostname cannot exist twice — delete the old kind first.
          deleteFirst: !hostnameChanged && !appChanged,
        };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const appName = output?.appName ?? appNameOf(olds?.app);
      const hostname = output?.hostname ?? olds?.hostname;
      if (appName === undefined || hostname === undefined) return undefined;
      const found = yield* getByHostname(appName, hostname);
      if (found === undefined) return undefined;
      return toAttrs(appName, found, hostname);
    }),

    list: Effect.fn(function* () {
      const apps = yield* listOwnedApps();
      const rows = yield* Effect.forEach(
        apps,
        (app) =>
          listAppCertificates(app.appName).pipe(
            Effect.map((certs) =>
              certs.flatMap((item) => {
                const attrs = toAttrsFromSummary(app.appName, item);
                return attrs === undefined ? [] : [attrs];
              }),
            ),
          ),
        { concurrency: 8 },
      );
      return rows.flat();
    }),

    reconcile: Effect.fn(function* ({ news, olds, output }) {
      const props = news ?? ({} as CertificateProps);
      const appName = appNameOf(props.app) ?? output?.appName;
      const hostname = props.hostname ?? output?.hostname;
      if (appName === undefined) {
        return yield* new CertificateAppMissing({
          hostname: hostname ?? "",
        });
      }
      if (hostname === undefined || hostname.length === 0) {
        return yield* new CertificateNotCreated({
          appName,
          hostname: "",
        });
      }

      const kind = desiredKind(props);

      // Observe by cached identity, then by desired hostname.
      let current =
        output?.hostname !== undefined
          ? yield* getByHostname(
              output.appName.length > 0 ? output.appName : appName,
              output.hostname,
            )
          : undefined;
      if (current === undefined && (output?.hostname !== hostname || output?.appName !== appName)) {
        current = yield* getByHostname(appName, hostname);
      }

      let createdThisPass = false;
      if (current === undefined) {
        if (kind === "custom") {
          const fullchain = props.fullchain;
          const privateKey = unwrapSecret(props.privateKey);
          const missing = requireCustomMaterial(hostname, fullchain, privateKey);
          if (missing !== undefined) return yield* missing;
          const created = yield* createCustom(appName, hostname, fullchain!, privateKey!);
          current = created ?? (yield* getByHostname(appName, hostname));
        } else {
          const created = yield* createAcme(appName, hostname);
          current = created ?? (yield* getByHostname(appName, hostname));
        }
        createdThisPass = true;
      }

      if (current === undefined) {
        return yield* new CertificateNotCreated({ appName, hostname });
      }

      if (kind === "custom") {
        const fullchain = props.fullchain;
        const privateKey = unwrapSecret(props.privateKey);
        const missing = requireCustomMaterial(hostname, fullchain, privateKey);
        if (missing !== undefined) return yield* missing;
        const previousChain = olds?.fullchain;
        const previousKey = unwrapSecret(olds?.privateKey);
        const materialChanged =
          olds === undefined ||
          normalizePem(fullchain) !== normalizePem(previousChain) ||
          normalizePem(privateKey) !== normalizePem(previousKey);
        if (!createdThisPass && materialChanged) {
          const upserted = yield* createCustom(appName, hostname, fullchain!, privateKey!);
          if (upserted === undefined) {
            yield* replaceCustom(appName, hostname, fullchain!, privateKey!);
          }
          current = upserted ?? (yield* getByHostname(appName, hostname)) ?? current;
        }
      } else if (current.configured !== true) {
        const checked = yield* machines
          .checkAppCertificate({
            app_name: appName,
            hostname,
          })
          .pipe(Effect.catchTag(["NotFound", "BadRequest"], () => Effect.undefined));
        if (checked !== undefined) {
          current = checked;
        }
      }

      return toAttrs(appName, current, hostname);
    }),

    delete: Effect.fn(function* ({ output }) {
      const appName = output.appName;
      const hostname = output.hostname;
      if (appName.length === 0 || hostname.length === 0) return;
      yield* machines
        .deleteAppCertificate({
          app_name: appName,
          hostname,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
      yield* waitUntilGone(appName, hostname);
    }),
  });