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

package/src/Client.ts

@@ -0,0 +1,405 @@
+/**
+ * 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 })),
+    );
+  });

package/src/Der.ts

@@ -0,0 +1,157 @@
+/**
+ * A minimal DER encoder/decoder — just enough ASN.1 for a PKCS#10
+ * certificate request (encode) and reading a certificate's serial,
+ * validity, issuer and subject alternative names (decode). Pure
+ * TypeScript; no native code, no dependency, works on workerd.
+ *
+ * @internal
+ */
+
+export const concat = (...parts: ReadonlyArray<Uint8Array>): Uint8Array => {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+};
+
+const encodeLength = (n: number): Uint8Array => {
+  if (n < 0x80) return Uint8Array.of(n);
+  if (n < 0x100) return Uint8Array.of(0x81, n);
+  if (n < 0x10000) return Uint8Array.of(0x82, n >>> 8, n & 0xff);
+  return Uint8Array.of(0x83, n >>> 16, (n >>> 8) & 0xff, n & 0xff);
+};
+
+/** Tag-length-value. */
+export const tlv = (tag: number, body: Uint8Array): Uint8Array =>
+  concat(Uint8Array.of(tag), encodeLength(body.length), body);
+
+export const sequence = (...items: ReadonlyArray<Uint8Array>) => tlv(0x30, concat(...items));
+export const set = (...items: ReadonlyArray<Uint8Array>) => tlv(0x31, concat(...items));
+export const octetString = (body: Uint8Array) => tlv(0x04, body);
+export const bitString = (body: Uint8Array) => tlv(0x03, concat(Uint8Array.of(0), body));
+export const nullValue = () => Uint8Array.of(0x05, 0x00);
+export const ia5String = (text: string) => tlv(0x16, new TextEncoder().encode(text));
+export const utf8String = (text: string) => tlv(0x0c, new TextEncoder().encode(text));
+/** Context-specific constructed tag `[n]` (implicit or explicit, caller's choice of body). */
+export const contextTag = (n: number, body: Uint8Array) => tlv(0xa0 | n, body);
+/** Context-specific primitive tag `[n]` (e.g. GeneralName dNSName is `[2]`). */
+export const contextPrimitive = (n: number, body: Uint8Array) => tlv(0x80 | n, body);
+
+/** INTEGER from a non-negative number or big-endian magnitude bytes. */
+export const integer = (value: number | Uint8Array): Uint8Array => {
+  if (typeof value === "number") {
+    if (value === 0) return tlv(0x02, Uint8Array.of(0));
+    const bytes: number[] = [];
+    let n = value;
+    while (n > 0) {
+      bytes.unshift(n & 0xff);
+      n = Math.floor(n / 256);
+    }
+    if (bytes[0]! & 0x80) bytes.unshift(0);
+    return tlv(0x02, Uint8Array.from(bytes));
+  }
+  let start = 0;
+  while (start < value.length - 1 && value[start] === 0) start++;
+  const magnitude = value.subarray(start);
+  return tlv(0x02, magnitude[0]! & 0x80 ? concat(Uint8Array.of(0), magnitude) : magnitude);
+};
+
+/** OBJECT IDENTIFIER from dotted notation. */
+export const oid = (dotted: string): Uint8Array => {
+  const parts = dotted.split(".").map(Number);
+  const bytes: number[] = [parts[0]! * 40 + parts[1]!];
+  for (const part of parts.slice(2)) {
+    const stack: number[] = [part & 0x7f];
+    let n = Math.floor(part / 128);
+    while (n > 0) {
+      stack.unshift((n & 0x7f) | 0x80);
+      n = Math.floor(n / 128);
+    }
+    bytes.push(...stack);
+  }
+  return tlv(0x06, Uint8Array.from(bytes));
+};
+
+// =============================================================================
+// Decoding
+// =============================================================================
+
+export interface Node {
+  readonly tag: number;
+  /** Offset of the first content byte. */
+  readonly start: number;
+  /** Offset one past the last content byte. */
+  readonly end: number;
+  readonly bytes: Uint8Array;
+}
+
+export const read = (bytes: Uint8Array, offset: number): Node => {
+  const tag = bytes[offset]!;
+  let cursor = offset + 1;
+  let length = bytes[cursor++]!;
+  if (length & 0x80) {
+    const count = length & 0x7f;
+    length = 0;
+    for (let i = 0; i < count; i++) length = length * 256 + bytes[cursor++]!;
+  }
+  return { tag, start: cursor, end: cursor + length, bytes };
+};
+
+/** The children of a constructed node, in order. */
+export const children = (node: Node): Node[] => {
+  const out: Node[] = [];
+  let cursor = node.start;
+  while (cursor < node.end) {
+    const child = read(node.bytes, cursor);
+    out.push(child);
+    cursor = child.end;
+  }
+  return out;
+};
+
+export const content = (node: Node): Uint8Array => node.bytes.subarray(node.start, node.end);
+
+export const decodeOid = (node: Node): string => {
+  const body = content(node);
+  const first = body[0]!;
+  const parts = [Math.floor(first / 40), first % 40];
+  let n = 0;
+  for (let i = 1; i < body.length; i++) {
+    n = n * 128 + (body[i]! & 0x7f);
+    if ((body[i]! & 0x80) === 0) {
+      parts.push(n);
+      n = 0;
+    }
+  }
+  // OIDs under joint-iso-itu-t(2) can have a first arc ≥ 2 with large second arcs.
+  if (first >= 80) {
+    parts[0] = 2;
+    parts[1] = first - 80;
+  }
+  return parts.join(".");
+};
+
+/** Parse UTCTime (`YYMMDDHHMMSSZ`) or GeneralizedTime (`YYYYMMDDHHMMSSZ`). */
+export const decodeTime = (node: Node): Date => {
+  const text = new TextDecoder().decode(content(node));
+  const generalized = node.tag === 0x18;
+  const year = generalized
+    ? Number(text.slice(0, 4))
+    : (() => {
+        const yy = Number(text.slice(0, 2));
+        return yy < 50 ? 2000 + yy : 1900 + yy;
+      })();
+  const rest = generalized ? text.slice(4) : text.slice(2);
+  const month = Number(rest.slice(0, 2));
+  const day = Number(rest.slice(2, 4));
+  const hour = Number(rest.slice(4, 6));
+  const minute = Number(rest.slice(6, 8));
+  const second = Number(rest.slice(8, 10)) || 0;
+  return new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+};
+
+export const toHex = (bytes: Uint8Array): string =>
+  Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");