@alchemy.run/acme 0.0.0 → 2.0.0-beta.85

package/src/Dns.ts

@@ -0,0 +1,227 @@
+/**
+ * TXT propagation checks.
+ *
+ * Public recursive resolvers are a poor oracle: they cache negative
+ * answers for the zone's SOA minimum (30 minutes is common) and old
+ * record sets past their TTL, so a challenge value published a moment ago
+ * can stay invisible for far longer than the CA takes to validate. Where
+ * `node:dns` is available (deploy time, Fly Machines) the check therefore
+ * asks the zone's **authoritative** nameservers directly — the same
+ * servers the CA asks. Networks can intercept port 53, so DNS over HTTPS
+ * also checks for the exact challenge value. A stale recursive cache must
+ * not veto a positive answer; the CA performs its own validation.
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Schedule from "effect/Schedule";
+import { DnsPropagationTimeout } from "./Errors.ts";
+
+export interface PropagationOptions {
+  /**
+   * Wait before the first lookup to avoid caching an unpublished record.
+   * Outside the polling budget. Cloudflare defaults to 60 seconds.
+   * @default "0 seconds"
+   */
+  readonly initialDelay?: Duration.Input | undefined;
+  /**
+   * Extra wait after the record is seen (or, for solvers that skip the
+   * check, the whole wait): anycast edges lag the first one that answers.
+   * @default "5 seconds"
+   */
+  readonly delay?: Duration.Input | undefined;
+  /**
+   * DNS-over-HTTPS JSON endpoints to use instead of automatic discovery.
+   * When supplied, every resolver must return the record. Automatic lookup
+   * accepts all discovered nameservers or any default DoH resolver.
+   * @default Cloudflare (1.1.1.1) and Google public DNS
+   */
+  readonly resolvers?: ReadonlyArray<string> | undefined;
+  /** Polling budget. @default "45 seconds" */
+  readonly timeout?: Duration.Input | undefined;
+  /** Polling interval. @default "3 seconds" */
+  readonly interval?: Duration.Input | undefined;
+}
+
+export const DEFAULT_PROPAGATION_DELAY: Duration.Input = "5 seconds";
+
+/** Sleep `options.delay` (default 5 seconds). */
+export const propagationDelay = (options: PropagationOptions = {}): Effect.Effect<void> =>
+  Effect.sleep(options.delay ?? DEFAULT_PROPAGATION_DELAY);
+
+// =============================================================================
+// Authoritative lookup (node:dns where available)
+// =============================================================================
+
+interface NodeDns {
+  readonly resolveNs: (name: string) => Promise<string[]>;
+  readonly resolve4: (name: string) => Promise<string[]>;
+  readonly Resolver: new () => {
+    setServers(servers: string[]): void;
+    resolveTxt(name: string): Promise<string[][]>;
+  };
+}
+
+const nodeDns: Effect.Effect<NodeDns | undefined> = Effect.tryPromise(
+  () => import("node:dns/promises") as unknown as Promise<NodeDns>,
+).pipe(
+  Effect.map((mod) =>
+    typeof mod?.Resolver === "function" && typeof mod.resolveNs === "function" ? mod : undefined,
+  ),
+  Effect.orElseSucceed(() => undefined),
+);
+
+/** The zone apex's nameserver IPv4s for `fqdn`, or `[]` when unknown. */
+const authoritativeServers = (dns: NodeDns, fqdn: string): Effect.Effect<ReadonlyArray<string>> =>
+  Effect.gen(function* () {
+    const labels = fqdn.replace(/\.$/, "").split(".");
+    for (let i = 0; i < labels.length - 1; i++) {
+      const candidate = labels.slice(i).join(".");
+      const names = yield* Effect.tryPromise(() => dns.resolveNs(candidate)).pipe(
+        Effect.orElseSucceed(() => [] as string[]),
+      );
+      if (names.length === 0) continue;
+      const addresses = yield* Effect.forEach(
+        names,
+        (name) =>
+          Effect.tryPromise(() => dns.resolve4(name)).pipe(
+            Effect.orElseSucceed(() => [] as string[]),
+          ),
+        { concurrency: "unbounded" },
+      );
+      return addresses.flat();
+    }
+    return [];
+  });
+
+/** TXT values requested from one nameserver (port 53 may be intercepted). */
+const resolveTxtAt = (
+  dns: NodeDns,
+  server: string,
+  fqdn: string,
+): Effect.Effect<ReadonlyArray<string>> =>
+  Effect.gen(function* () {
+    const resolver = yield* Effect.sync(() => new dns.Resolver());
+    yield* Effect.sync(() => resolver.setServers([server]));
+    const records = yield* Effect.tryPromise(() => resolver.resolveTxt(fqdn));
+    return records.map((chunks) => chunks.join(""));
+  }).pipe(
+    Effect.timeout("3 seconds"),
+    Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+  );
+
+export const DEFAULT_RESOLVERS: ReadonlyArray<string> = [
+  "https://cloudflare-dns.com/dns-query",
+  "https://dns.google/resolve",
+];
+
+interface DohAnswer {
+  readonly type?: number;
+  readonly data?: string;
+}
+
+const unquote = (data: string): string =>
+  (data.match(/"((?:[^"\\]|\\.)*)"/g) ?? [data])
+    .map((part) => part.replace(/^"|"$/g, "").replace(/\\"/g, '"'))
+    .join("");
+
+/**
+ * TXT values for `fqdn` from one DoH resolver. Any transport or parse
+ * failure reads as "no records yet".
+ */
+export const resolveTxt = (
+  resolver: string,
+  fqdn: string,
+): Effect.Effect<ReadonlyArray<string>, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.get(resolver).pipe(
+      HttpClientRequest.setUrlParams({ name: fqdn, type: "TXT" }),
+      HttpClientRequest.setHeader("Accept", "application/dns-json"),
+    );
+    const response = yield* client.execute(request);
+    const body = (yield* response.json) as { Answer?: DohAnswer[] };
+    return (body.Answer ?? [])
+      .filter((answer) => answer.type === 16 && typeof answer.data === "string")
+      .map((answer) => unquote(answer.data!));
+  }).pipe(
+    Effect.timeout("3 seconds"),
+    Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+  );
+
+/**
+ * Wait `initialDelay`, then poll for the exact challenge value and wait
+ * `delay`. Explicit resolvers must all agree; automatic lookup accepts all
+ * discovered nameservers or a positive default DoH answer. Discovery and
+ * polling share `timeout`; the delays before and after are outside it.
+ */
+export const waitForTxt = (
+  fqdn: string,
+  value: string,
+  options: PropagationOptions = {},
+): Effect.Effect<void, DnsPropagationTimeout, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const interval = options.interval ?? "3 seconds";
+    const timeout = options.timeout ?? "45 seconds";
+    // Bounded by `timeout` below, so poll for the caller's whole budget.
+    const attempts = Math.max(
+      1,
+      Math.ceil(Duration.toMillis(timeout) / Duration.toMillis(interval)),
+    );
+    yield* Effect.sleep(options.initialDelay ?? "0 seconds");
+    const propagated = yield* Effect.gen(function* () {
+      // Explicit resolvers must work even when node:dns is available.
+      const dns = options.resolvers === undefined ? yield* nodeDns : undefined;
+      const servers =
+        dns === undefined
+          ? []
+          : yield* authoritativeServers(dns, fqdn).pipe(
+              Effect.timeout("5 seconds"),
+              Effect.orElseSucceed(() => [] as ReadonlyArray<string>),
+            );
+      const check = Effect.all(
+        {
+          direct: Effect.all(
+            dns === undefined
+              ? []
+              : servers.map((server) =>
+                  resolveTxtAt(dns, server, fqdn).pipe(
+                    Effect.map((values) => values.includes(value)),
+                  ),
+                ),
+            { concurrency: "unbounded" },
+          ),
+          doh: Effect.forEach(
+            options.resolvers ?? DEFAULT_RESOLVERS,
+            (resolver) =>
+              resolveTxt(resolver, fqdn).pipe(Effect.map((values) => values.includes(value))),
+            { concurrency: "unbounded" },
+          ),
+        },
+        { concurrency: "unbounded" },
+      ).pipe(
+        Effect.map(({ direct, doh }) =>
+          options.resolvers !== undefined
+            ? doh.length > 0 && doh.every(Boolean)
+            : (direct.length > 0 && direct.every(Boolean)) || doh.some(Boolean),
+        ),
+      );
+      return yield* check.pipe(
+        Effect.repeat({
+          schedule: Schedule.spaced(interval),
+          until: (seen) => seen,
+          times: attempts,
+        }),
+      );
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: timeout,
+        orElse: () => Effect.fail(new DnsPropagationTimeout({ fqdn, value })),
+      }),
+    );
+    if (!propagated) {
+      return yield* new DnsPropagationTimeout({ fqdn, value });
+    }
+    yield* propagationDelay(options);
+  });

package/src/DnsSolver.ts

@@ -0,0 +1,109 @@
+/**
+ * DNS-01 solvers: how the ACME flow publishes `_acme-challenge` TXT
+ * records.
+ *
+ * A solver has two forms:
+ *
+ * - a **descriptor** — plain, serializable data in a resource's props
+ *   (`{ type: "Cloudflare.DNS", zoneId }`) that survives state and the RPC
+ *   boundary. Each DNS solver has a constructor
+ *   (`Cloudflare.ACME.ZoneSolver(zone)`) and a layer registering the
+ *   matching implementation, so the ACME provider never imports a DNS SDK
+ *   itself.
+ * - a **runtime solver** — the {@link DnsSolver} interface a running
+ *   Worker or Service hands to `IssueCertificate.issue`, built from a
+ *   runtime DNS write client (`Cloudflare.ACME.zoneSolver(dns)`).
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import type { PropagationOptions } from "./Dns.ts";
+import {
+  DnsSolverNotRegistered,
+  type DnsPropagationTimeout,
+  type DnsSolverError,
+} from "./Errors.ts";
+
+/** A challenge record to publish: the `_acme-challenge.<name>` FQDN and its TXT value. */
+export interface DnsChallengeRecord {
+  readonly fqdn: string;
+  readonly value: string;
+}
+
+/** Runtime DNS-01 solver. `R` is whatever context the underlying client needs. */
+export interface DnsSolver<R = never> {
+  /** Publish `value` as a TXT record at `fqdn`. Idempotent. */
+  readonly present: (record: DnsChallengeRecord) => Effect.Effect<void, DnsSolverError, R>;
+  /** Remove the record published by `present`. Idempotent; runs in a finalizer. */
+  readonly cleanup: (record: DnsChallengeRecord) => Effect.Effect<void, DnsSolverError, R>;
+  /**
+   * Wait until the record is visible. Defaults to polling public DNS over
+   * HTTPS; a solver for a private DNS (tests, split-horizon zones) overrides it.
+   */
+  readonly propagated?:
+    | ((
+        record: DnsChallengeRecord,
+        options: PropagationOptions,
+      ) => Effect.Effect<void, DnsSolverError | DnsPropagationTimeout, R | HttpClient.HttpClient>)
+    | undefined;
+}
+
+/**
+ * Serializable solver description stored in `ACME.Certificate` props.
+ * `type` selects the registered implementation; the rest is provider data.
+ */
+export interface DnsSolverDescriptor {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** Builds a runtime solver from a descriptor at reconcile time. */
+export type DnsSolverFactory = (
+  descriptor: DnsSolverDescriptor,
+) => Effect.Effect<DnsSolver, DnsSolverError>;
+
+const solverService = (type: string) =>
+  Context.Service<DnsSolverFactory>(`alchemy/ACME/DnsSolver/${type}`);
+
+/** Resolve the registered implementation for a descriptor. */
+export const resolveDnsSolver = (
+  descriptor: DnsSolverDescriptor,
+): Effect.Effect<DnsSolver, DnsSolverNotRegistered | DnsSolverError> =>
+  Effect.gen(function* () {
+    const factory = yield* Effect.serviceOption(solverService(descriptor.type));
+    if (Option.isNone(factory)) {
+      return yield* new DnsSolverNotRegistered({ type: descriptor.type });
+    }
+    return yield* factory.value(descriptor);
+  });
+
+/** A solver whose methods run with `context` provided (drops `R`). */
+export const provideSolver = <R>(solver: DnsSolver<R>, context: Context.Context<R>): DnsSolver => ({
+  present: (record) => solver.present(record).pipe(Effect.provideContext(context)),
+  cleanup: (record) => solver.cleanup(record).pipe(Effect.provideContext(context)),
+  propagated:
+    solver.propagated === undefined
+      ? undefined
+      : (record, options) =>
+          solver.propagated!(record, options).pipe(Effect.provideContext(context)),
+});
+
+/**
+ * Register a solver implementation from a `providers()` layer, capturing
+ * whatever services `R` the solver needs from that layer's own context so
+ * the ACME provider can run it without knowing about the DNS provider.
+ */
+export const dnsSolverLayer = <R>(
+  type: string,
+  make: (descriptor: DnsSolverDescriptor) => Effect.Effect<DnsSolver<R>, DnsSolverError>,
+): Layer.Layer<DnsSolverFactory, never, R> =>
+  Layer.effect(
+    solverService(type),
+    Effect.gen(function* () {
+      const context = yield* Effect.context<R>();
+      return (descriptor: DnsSolverDescriptor) =>
+        make(descriptor).pipe(Effect.map((solver) => provideSolver(solver, context)));
+    }),
+  );

package/src/Errors.ts

@@ -0,0 +1,90 @@
+import * as Data from "effect/Data";
+
+/** A problem the CA attached to an order or one of its identifiers. */
+export interface IdentifierProblem {
+  /** The identifier the problem concerns, when the CA said. */
+  readonly identifier?: string | undefined;
+  /** The `urn:ietf:params:acme:error:*` type. */
+  readonly type?: string | undefined;
+  /** Human-readable detail from the CA. */
+  readonly detail?: string | undefined;
+}
+
+/**
+ * The CA moved the order to `invalid`. Carries the problem documents the
+ * order and its authorizations reported, one per failed identifier where
+ * the CA said which.
+ */
+export class OrderInvalid extends Data.TaggedError("ACME.OrderInvalid")<{
+  readonly orderUrl: string;
+  readonly problems: ReadonlyArray<IdentifierProblem>;
+}> {
+  override get message() {
+    const details = this.problems
+      .map((p) => [p.identifier, p.type, p.detail].filter(Boolean).join(": "))
+      .join("; ");
+    return `ACME order ${this.orderUrl} is invalid${details ? `: ${details}` : ""}`;
+  }
+}
+
+/** The CA rejected the DNS-01 challenge for one identifier. */
+export class ChallengeFailed extends Data.TaggedError("ACME.ChallengeFailed")<{
+  readonly identifier: string;
+  readonly type?: string | undefined;
+  readonly detail?: string | undefined;
+}> {
+  override get message() {
+    return `DNS-01 challenge for ${this.identifier} failed${this.detail ? `: ${this.detail}` : ""}`;
+  }
+}
+
+/** The CA offered no `dns-01` challenge for an identifier. */
+export class ChallengeUnsupported extends Data.TaggedError("ACME.ChallengeUnsupported")<{
+  readonly identifier: string;
+  readonly offered: ReadonlyArray<string>;
+}> {
+  override get message() {
+    return `The CA offered no dns-01 challenge for ${this.identifier} (offered: ${this.offered.join(", ") || "none"})`;
+  }
+}
+
+/** The order never reached a terminal state within the polling budget. */
+export class OrderTimeout extends Data.TaggedError("ACME.OrderTimeout")<{
+  readonly orderUrl: string;
+  readonly status: string;
+}> {
+  override get message() {
+    return `ACME order ${this.orderUrl} is still "${this.status}" after the polling budget`;
+  }
+}
+
+/** The `_acme-challenge` TXT record never became visible to public resolvers. */
+export class DnsPropagationTimeout extends Data.TaggedError("ACME.DnsPropagationTimeout")<{
+  readonly fqdn: string;
+  readonly value: string;
+}> {
+  override get message() {
+    return `TXT ${this.fqdn} did not propagate within the wait budget`;
+  }
+}
+
+/** A DNS solver could not publish or remove a challenge record. */
+export class DnsSolverError extends Data.TaggedError("ACME.DnsSolverError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/** A solver descriptor names a `type` no registered DNS provider handles. */
+export class DnsSolverNotRegistered extends Data.TaggedError("ACME.DnsSolverNotRegistered")<{
+  readonly type: string;
+}> {
+  override get message() {
+    return `No DNS-01 solver is registered for "${this.type}". Include ACME.providers() in the stack.`;
+  }
+}
+
+/** Key generation, CSR encoding or certificate parsing failed. */
+export class PkiError extends Data.TaggedError("ACME.PkiError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}

package/src/IssueCertificate.ts

@@ -0,0 +1,89 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Account } from "./Account.ts";
+import type {
+  IssueError,
+  IssueRequest,
+  IssuedCertificate,
+  RevokeError,
+  RevokeRequest,
+} from "./Client.ts";
+
+/**
+ * Issue (and revoke) certificates at runtime as an {@link Account} — for
+ * services that terminate TLS themselves and need certificates on demand,
+ * like a relay minting `*.<tenant>.example.com` when a tenant first
+ * connects.
+ *
+ * Init transports the account's directory URL, account URL and redacted
+ * private key through resource Outputs. Protect the runtime and state store
+ * as secret material. The caller chooses where to store the issued PEMs.
+ *
+ * ### Issue on demand
+ * Publish the DNS-01 record through any runtime DNS write client wrapped
+ * as a solver (`Cloudflare.ACME.zoneSolver(dns)`).
+ *
+ * **Example:** Mint a wildcard from a Fly Service and upload it to its App
+ * ```typescript
+ * export default class Relay extends Fly.Service<Relay>()(
+ *   "Relay",
+ *   { app: RelayApp, main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const acme = yield* ACME.IssueCertificate(ZeroSsl);
+ *     const dns = yield* Cloudflare.DNS.WriteDns(Zone);
+ *     const certs = yield* Fly.WriteCertificates(RelayApp);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const issued = yield* acme.issue({
+ *           identifiers: ["*.tenant.example.com"],
+ *           solver: Cloudflare.ACME.zoneSolver(dns),
+ *         });
+ *         yield* certs.upload({
+ *           hostname: "*.tenant.example.com",
+ *           fullchain: issued.chain,
+ *           privateKey: issued.privateKey,
+ *         });
+ *         return HttpServerResponse.text("ok");
+ *       }),
+ *     };
+ *   }).pipe(
+ *     Effect.provide(ACME.IssueCertificateHttp),
+ *     Effect.provide(Cloudflare.DNS.WriteDnsHttp),
+ *     Effect.provide(Fly.WriteCertificatesHttp),
+ *   ),
+ * ) {}
+ * ```
+ *
+ * ### Rate limits
+ * The SDK retry policy applies to individual requests. Apply
+ * `Acme.Retry.none` from `@distilled.cloud/acme` to surface failures
+ * immediately; `AcmeRateLimited.retryAfter` carries the CA's retry hint.
+ *
+ * ### Which CA from a Cloudflare Worker
+ * CA reachability depends on the host's egress. Let's Encrypt has returned
+ * TLS failures from deployed Cloudflare Workers in live testing; the
+ * deployed-Worker example uses ZeroSSL instead. Verify the selected CA
+ * from the runtime where issuance will run.
+ *
+ * @binding
+ * @product Certificate
+ * @category Certificates
+ */
+export interface IssueCertificate extends Binding.Service<
+  IssueCertificate,
+  "ACME.IssueCertificate",
+  (account: Account) => Effect.Effect<IssueCertificateClient>
+> {}
+
+export const IssueCertificate = Binding.Service<IssueCertificate>("ACME.IssueCertificate");
+
+/** Runtime issuance client bound to one account. */
+export interface IssueCertificateClient {
+  /** Order, solve DNS-01, finalize and download a certificate. */
+  issue<R = never>(
+    request: IssueRequest<R>,
+  ): Effect.Effect<IssuedCertificate, IssueError, RuntimeContext | R>;
+  /** Revoke a certificate (`AcmeAlreadyRevoked` counts as success). */
+  revoke(request: RevokeRequest): Effect.Effect<void, RevokeError, RuntimeContext>;
+}

package/src/IssueCertificateHttp.ts

@@ -0,0 +1,67 @@
+import * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { Account } from "./Account.ts";
+import {
+  accountLayer,
+  issueCertificate,
+  revokeCertificate,
+  type AccountCredentials,
+} from "./Client.ts";
+import { IssueCertificate, type IssueCertificateClient } from "./IssueCertificate.ts";
+
+/**
+ * Implementation of {@link IssueCertificate}: the account's directory
+ * URL, account URL and private key are bound into the host at deploy time
+ * and read back at runtime; every call signs with them over HTTPS.
+ *
+ * Provide it on the Worker / Service / Action Effect.
+ *
+ * ### Provide the layer
+ * **Example:** On a Fly Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const acme = yield* ACME.IssueCertificate(LetsEncrypt);
+ *   // ...
+ * }).pipe(Effect.provide(ACME.IssueCertificateHttp))
+ * ```
+ *
+ * @layer
+ * @product Certificate
+ * @provides ACME.IssueCertificate
+ */
+export const IssueCertificateHttp = Layer.succeed(
+  IssueCertificate,
+  Effect.fn(function* (account: Account) {
+    const directoryUrl = yield* account.directoryUrl;
+    const accountUrl = yield* account.accountUrl;
+    const trustedRoot = yield* account.trustedRoot.pipe(Output.map((root) => root ?? ""));
+    const privateKey = yield* account.privateKey;
+    const credentials = Effect.all({
+      directoryUrl,
+      trustedRoot,
+      accountUrl,
+      privateKey,
+    }).pipe(
+      Effect.map((bound): AccountCredentials => ({
+        ca: {
+          directoryUrl: bound.directoryUrl,
+          trustedRoot: bound.trustedRoot || undefined,
+        },
+        accountKey: bound.privateKey,
+        accountUrl: bound.accountUrl,
+      })),
+    );
+    const client: IssueCertificateClient = {
+      issue: Effect.fn("ACME.IssueCertificate.issue")(function* (request) {
+        const creds = yield* credentials;
+        return yield* issueCertificate(request).pipe(Effect.provide(accountLayer(creds)));
+      }),
+      revoke: Effect.fn("ACME.IssueCertificate.revoke")(function* (request) {
+        const creds = yield* credentials;
+        return yield* revokeCertificate(request).pipe(Effect.provide(accountLayer(creds)));
+      }),
+    };
+    return client;
+  }),
+);