@distilled.cloud/acme 0.0.0-placeholder → 1.0.0-rc.13

package/lib/traits.js

@@ -0,0 +1,13 @@
+/**
+ * ACME SDK trait surface — hand-written.
+ *
+ * Re-exports the generic protocol traits from core so generated operations
+ * import everything from one place (`import * as T from "../traits.ts"`).
+ * ACME is JWS-signed JSON, so
+ * there are no ACME-specific traits — the REST-protocol traits
+ * (`SensitiveValue` / `RawResponse` / `RawResponseRoot`) come from
+ * `core/protocol-rest`.
+ */
+export { SensitiveValue, RawResponse, RawResponseRoot, sensitiveValueSymbol, rawResponseSymbol, rawResponseRootSymbol, } from "@distilled.cloud/core/protocol-rest";
+export { Body, Header, Query, Label, Http, ResponseCode, HttpBody, FormDataFile, KeyDictionary, UnionCases, applyErrorMatchers, getErrorMatchers, bodySymbol, headerSymbol, querySymbol, labelSymbol, httpSymbol, responseCodeSymbol, httpBodySymbol, formDataFileSymbol, keyDictionarySymbol, unionCasesSymbol, errorMatchersSymbol, } from "@distilled.cloud/core/trait";
+//# sourceMappingURL=traits.js.map

package/lib/traits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,cAAc,EACd,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EACL,IAAI,EACJ,MAAM,EACN,KAAK,EACL,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAGhB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,6BAA6B,CAAC"}

package/package.json

@@ -1,15 +1,83 @@
 {
   "name": "@distilled.cloud/acme",
-  "version": "0.0.0-placeholder",
-  "description": "Placeholder package for initial npm registration.",
-  "license": "Apache-2.0",
+  "version": "1.0.0-rc.13",
   "repository": {
     "type": "git",
     "url": "https://github.com/alchemy-run/distilled",
     "directory": "packages/acme"
   },
-  "publishConfig": {
-    "access": "public",
-    "tag": "placeholder"
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "module": "src/index.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "worker": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./Credentials": {
+      "types": "./lib/credentials.d.ts",
+      "bun": "./src/credentials.ts",
+      "worker": "./src/credentials.ts",
+      "default": "./lib/credentials.js"
+    },
+    "./Errors": {
+      "types": "./lib/errors.d.ts",
+      "bun": "./src/errors.ts",
+      "worker": "./src/errors.ts",
+      "default": "./lib/errors.js"
+    },
+    "./Jose": {
+      "types": "./lib/jose.d.ts",
+      "bun": "./src/jose.ts",
+      "worker": "./src/jose.ts",
+      "default": "./lib/jose.js"
+    },
+    "./Protocol": {
+      "types": "./lib/protocol.d.ts",
+      "bun": "./src/protocol.ts",
+      "worker": "./src/protocol.ts",
+      "default": "./lib/protocol.js"
+    },
+    "./Retry": {
+      "types": "./lib/retry.d.ts",
+      "bun": "./src/retry.ts",
+      "worker": "./src/retry.ts",
+      "default": "./lib/retry.js"
+    },
+    "./Traits": {
+      "types": "./lib/traits.d.ts",
+      "bun": "./src/traits.ts",
+      "worker": "./src/traits.ts",
+      "default": "./lib/traits.js"
+    },
+    "./acme": {
+      "types": "./lib/services/acme.d.ts",
+      "bun": "./src/services/acme.ts",
+      "worker": "./src/services/acme.ts",
+      "default": "./lib/services/acme.js"
+    }
+  },
+  "dependencies": {
+    "@distilled.cloud/core": "1.0.0-rc.13"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "@types/node": "26.2.0",
+    "@effect/platform-bun": "^4.0.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "generate": "bun scripts/generate.ts",
+    "typecheck": "tsc -p tsconfig.json"
   }
-}
+}

package/src/credentials.ts

@@ -0,0 +1,106 @@
+/**
+ * ACME credentials — hand-written.
+ *
+ * An ACME "credential" is the **account key**: a private JWK that signs
+ * every request. The CA is addressed by its **directory URL** (Let's
+ * Encrypt, ZeroSSL, Google Trust Services and Pebble differ only there),
+ * plus, for CAs that require it, an **External Account Binding** (key id +
+ * HMAC key from the CA's dashboard) presented once on `newAccount`.
+ *
+ * The `Credentials` service holds an *effect* that resolves the current
+ * credentials, so the protocol picks up a rotated key or a newly learned
+ * account URL per request.
+ */
+import { ConfigError } from "@distilled.cloud/core/errors";
+import * as EffectConfig from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+
+/** Well-known ACME directories. */
+export const Directories = {
+  LetsEncrypt: "https://acme-v02.api.letsencrypt.org/directory",
+  LetsEncryptStaging: "https://acme-staging-v02.api.letsencrypt.org/directory",
+  ZeroSSL: "https://acme.zerossl.com/v2/DV90",
+  GoogleTrustServices: "https://dv.acme-v02.api.pki.goog/directory",
+  GoogleTrustServicesStaging: "https://dv.acme-v02.test-api.pki.goog/directory",
+} as const;
+
+export interface ExternalAccountBinding {
+  /** The CA-issued EAB key id. */
+  readonly keyId: string;
+  /** The CA-issued base64url HMAC key. */
+  readonly hmacKey: Redacted.Redacted<string>;
+}
+
+export interface Config {
+  /** The CA's directory URL. */
+  readonly directoryUrl: string;
+  /**
+   * The account's private key as a JSON Web Key (JSON text). ES256 (`EC`
+   * P-256) by default; RS256 (`RSA`) is accepted.
+   */
+  readonly accountKey: Redacted.Redacted<string>;
+  /**
+   * The account URL the CA assigned (`Location` of `newAccount`). Sent as
+   * `kid` on every request once known; `newAccount` uses the bare JWK.
+   */
+  readonly accountUrl?: string | undefined;
+  /** EAB for CAs that require it (ZeroSSL, Google Trust Services). */
+  readonly externalAccountBinding?: ExternalAccountBinding | undefined;
+}
+
+export class Credentials extends Context.Service<
+  Credentials,
+  Effect.Effect<Config>
+>()("AcmeCredentials") {}
+
+/**
+ * Credentials from the environment:
+ *
+ * - `ACME_DIRECTORY_URL` (default: Let's Encrypt production)
+ * - `ACME_ACCOUNT_KEY` — the private JWK as JSON
+ * - `ACME_ACCOUNT_URL` — optional, once the account exists
+ * - `ACME_EAB_KID` / `ACME_EAB_HMAC_KEY` — optional EAB pair
+ */
+export const CredentialsFromEnv = Layer.succeed(
+  Credentials,
+  EffectConfig.all({
+    directoryUrl: EffectConfig.String("ACME_DIRECTORY_URL").pipe(
+      EffectConfig.withDefault(Directories.LetsEncrypt),
+    ),
+    accountKey: EffectConfig.Redacted("ACME_ACCOUNT_KEY"),
+    accountUrl: EffectConfig.option(EffectConfig.String("ACME_ACCOUNT_URL")),
+    eabKid: EffectConfig.option(EffectConfig.String("ACME_EAB_KID")),
+    eabHmac: EffectConfig.option(EffectConfig.Redacted("ACME_EAB_HMAC_KEY")),
+  }).pipe(
+    Effect.mapError(
+      () =>
+        new ConfigError({
+          message:
+            "ACME_ACCOUNT_KEY (a private JWK) is required; ACME_DIRECTORY_URL, ACME_ACCOUNT_URL, ACME_EAB_KID and ACME_EAB_HMAC_KEY are optional",
+        }),
+    ),
+    Effect.map(
+      ({ directoryUrl, accountKey, accountUrl, eabKid, eabHmac }): Config => ({
+        directoryUrl,
+        accountKey,
+        accountUrl: Option.getOrUndefined(accountUrl),
+        externalAccountBinding:
+          Option.isSome(eabKid) && Option.isSome(eabHmac)
+            ? { keyId: eabKid.value, hmacKey: eabHmac.value }
+            : undefined,
+      }),
+    ),
+    Effect.orDie,
+  ),
+);
+
+/** A fixed credentials layer (tests, and consumers that manage keys themselves). */
+export const layer = (config: Config | Effect.Effect<Config>) =>
+  Layer.succeed(
+    Credentials,
+    Effect.isEffect(config) ? config : Effect.succeed(config),
+  );

package/src/errors.ts

@@ -0,0 +1,101 @@
+/**
+ * ACME-specific error types.
+ *
+ * ACME reports failures as RFC 7807 problem documents whose `type` is a
+ * `urn:ietf:params:acme:error:*` URN (RFC 8555 §6.7). Every URN the SDK
+ * knows is a typed class in the generated service (patched onto the
+ * operations that raise it, matched on the URN by the protocol). This
+ * module holds the shared HTTP defaults and the package's own client
+ * errors.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+import type {
+  BadRequest as CoreBadRequest,
+  Conflict as CoreConflict,
+  DefaultErrors as CoreDefaultErrors,
+  Forbidden as CoreForbidden,
+  NotFound as CoreNotFound,
+} from "@distilled.cloud/core/errors";
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/**
+ * Unknown ACME error — a problem document whose `type` matches no typed
+ * class on the operation. Carries structured problem fields and a redacted
+ * body. Add newly observed URNs to the authored model.
+ */
+export class UnknownAcmeError extends Schema.TaggedError<UnknownAcmeError>()(
+  "UnknownAcmeError",
+  {
+    /** The problem `type` URN, when the body was a problem document. */
+    type: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.Number),
+    detail: Schema.optional(Schema.String),
+    subproblems: Schema.optional(Schema.Array(Schema.Unknown)),
+    body: Schema.Unknown,
+  },
+) {}
+
+/** Schema parse error wrapper. */
+export class AcmeParseError extends Schema.TaggedError<AcmeParseError>()(
+  "AcmeParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}
+
+/** The account key could not be parsed or used to sign (client-side). */
+export class JoseError extends Schema.TaggedError<JoseError>()("JoseError", {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Unknown),
+}).pipe(Category.withBadRequestError) {}
+
+/**
+ * The directory has no URL for the requested resource (a CA without
+ * `newAuthz`/`keyChange`, or a stale directory URL).
+ */
+export class DirectoryMissingResource extends Schema.TaggedError<DirectoryMissingResource>()(
+  "DirectoryMissingResource",
+  {
+    resource: Schema.String,
+    directoryUrl: Schema.String,
+  },
+).pipe(Category.withBadRequestError) {}
+
+/** Errors any ACME operation may surface beyond the core HTTP defaults. */
+export type ClientErrors =
+  | UnknownAcmeError
+  | AcmeParseError
+  | JoseError
+  | DirectoryMissingResource;
+
+/**
+ * Default ACME operation errors: the shared HTTP status errors from core plus
+ * the client errors above.
+ */
+export type DefaultErrors =
+  | CoreDefaultErrors
+  | CoreBadRequest
+  | CoreForbidden
+  | CoreNotFound
+  | CoreConflict
+  | ClientErrors;

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @distilled.cloud/acme — ACME (RFC 8555) SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the hand-authored
+ * Smithy model in `manual-specs/acme.json` (RFC 8555 — there is no vendor spec for
+ * a protocol). Everything else in this folder is hand-written: the
+ * JWS-signing protocol, credentials (account key + directory + EAB), JOSE
+ * helpers, retry and errors.
+ *
+ * @example
+ * ```ts
+ * import * as Acme from "@distilled.cloud/acme";
+ *
+ * const account = yield* Acme.acme.newAccount({
+ *   contact: ["mailto:ops@example.com"],
+ *   termsOfServiceAgreed: true,
+ * });
+ * const order = yield* Acme.acme.newOrder({
+ *   identifiers: [{ type: "dns", value: "*.example.com" }],
+ * });
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as Jose from "./jose.ts";
+export * as T from "./traits.ts";
+export * as Retry from "./retry.ts";
+export {
+  AcmeProtocol,
+  type AcmeOpError,
+  type AcmeOpContext,
+} from "./protocol.ts";
+export * from "./services/index.ts";

package/src/jose.ts

@@ -0,0 +1,234 @@
+/**
+ * JOSE helpers for ACME — hand-written, WebCrypto only (no native code).
+ *
+ * - account keys (ES256 P-256 by default, RS256 accepted)
+ * - JWS in the flattened JSON serialization every ACME POST carries
+ *   (RFC 8555 §6.2), including the HS256 External Account Binding
+ * - RFC 7638 JWK thumbprints, key authorizations and the DNS-01 TXT value
+ */
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { JoseError } from "./errors.ts";
+
+export type Algorithm = "ES256" | "RS256";
+
+export interface Jwk {
+  readonly kty: string;
+  readonly crv?: string;
+  readonly x?: string;
+  readonly y?: string;
+  readonly n?: string;
+  readonly e?: string;
+  readonly d?: string;
+  readonly [key: string]: unknown;
+}
+
+const encoder = new TextEncoder();
+
+export const base64url = (bytes: Uint8Array | ArrayBuffer): string => {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const byte of view) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+};
+
+export const base64urlDecode = (text: string): Uint8Array => {
+  const padded = text.replaceAll("-", "+").replaceAll("_", "/");
+  const binary = atob(padded + "=".repeat((4 - (padded.length % 4)) % 4));
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+};
+
+const base64urlJson = (value: unknown): string =>
+  base64url(encoder.encode(JSON.stringify(value)));
+
+const sha256 = (data: Uint8Array | string): Effect.Effect<Uint8Array> =>
+  Effect.promise(async () => {
+    const bytes = typeof data === "string" ? encoder.encode(data) : data;
+    return new Uint8Array(
+      await crypto.subtle.digest("SHA-256", bytes as Uint8Array<ArrayBuffer>),
+    );
+  });
+
+/** Detect the JWS algorithm for a JWK. */
+export const algorithmOf = (jwk: Jwk): Algorithm =>
+  jwk.kty === "RSA" ? "RS256" : "ES256";
+
+const importAlgorithm = (alg: Algorithm) =>
+  alg === "RS256"
+    ? { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }
+    : { name: "ECDSA", namedCurve: "P-256" };
+
+const signAlgorithm = (alg: Algorithm) =>
+  alg === "RS256"
+    ? { name: "RSASSA-PKCS1-v1_5" }
+    : { name: "ECDSA", hash: "SHA-256" };
+
+/** Generate a fresh account key as a private JWK (JSON text, Redacted). */
+export const generateAccountKey = (
+  alg: Algorithm = "ES256",
+): Effect.Effect<Redacted.Redacted<string>> =>
+  Effect.promise(async () => {
+    const pair = await crypto.subtle.generateKey(
+      alg === "RS256"
+        ? {
+            name: "RSASSA-PKCS1-v1_5",
+            modulusLength: 2048,
+            publicExponent: new Uint8Array([1, 0, 1]),
+            hash: "SHA-256",
+          }
+        : { name: "ECDSA", namedCurve: "P-256" },
+      true,
+      ["sign", "verify"],
+    );
+    const jwk = await crypto.subtle.exportKey("jwk", pair.privateKey);
+    return Redacted.make(JSON.stringify(jwk));
+  });
+
+/** Parse a private JWK from its JSON text. */
+export const parseJwk = (
+  key: Redacted.Redacted<string> | string,
+): Effect.Effect<Jwk, JoseError> =>
+  Effect.try({
+    try: () =>
+      JSON.parse(Redacted.isRedacted(key) ? Redacted.value(key) : key) as Jwk,
+    catch: (cause) =>
+      new JoseError({
+        message: "The account key is not a JSON Web Key.",
+        cause,
+      }),
+  });
+
+/** The public half of a JWK, with members in RFC 7638 canonical order. */
+export const publicJwk = (jwk: Jwk): Jwk =>
+  jwk.kty === "RSA"
+    ? { e: jwk.e, kty: "RSA", n: jwk.n }
+    : { crv: jwk.crv, kty: "EC", x: jwk.x, y: jwk.y };
+
+/** RFC 7638 JWK thumbprint (base64url SHA-256 of the canonical public JWK). */
+export const thumbprint = (jwk: Jwk): Effect.Effect<string> =>
+  sha256(JSON.stringify(publicJwk(jwk))).pipe(Effect.map(base64url));
+
+/** `<token>.<thumbprint>` — what a challenge proves the client holds. */
+export const keyAuthorization = (
+  token: string,
+  jwk: Jwk,
+): Effect.Effect<string> =>
+  thumbprint(jwk).pipe(Effect.map((print) => `${token}.${print}`));
+
+/** The TXT record value for a DNS-01 challenge: base64url(SHA-256(keyAuthorization)). */
+export const dnsChallengeValue = (
+  token: string,
+  jwk: Jwk,
+): Effect.Effect<string> =>
+  keyAuthorization(token, jwk).pipe(
+    Effect.flatMap(sha256),
+    Effect.map(base64url),
+  );
+
+export interface FlattenedJws {
+  readonly protected: string;
+  readonly payload: string;
+  readonly signature: string;
+}
+
+export interface SignOptions {
+  readonly jwk: Jwk;
+  readonly url: string;
+  readonly nonce: string;
+  /** Sent as `kid` when known; otherwise the public JWK is embedded. */
+  readonly kid?: string | undefined;
+  /** `undefined` produces a POST-as-GET (empty payload). */
+  readonly payload?: unknown;
+}
+
+/** Sign an ACME request body (RFC 8555 §6.2) with the account key. */
+export const signRequest = (
+  options: SignOptions,
+): Effect.Effect<FlattenedJws, JoseError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const alg = algorithmOf(options.jwk);
+      const header = {
+        alg,
+        nonce: options.nonce,
+        url: options.url,
+        ...(options.kid !== undefined
+          ? { kid: options.kid }
+          : { jwk: publicJwk(options.jwk) }),
+      };
+      const protectedB64 = base64urlJson(header);
+      const payloadB64 =
+        options.payload === undefined ? "" : base64urlJson(options.payload);
+      const key = await crypto.subtle.importKey(
+        "jwk",
+        options.jwk as JsonWebKey,
+        importAlgorithm(alg),
+        false,
+        ["sign"],
+      );
+      const signature = await crypto.subtle.sign(
+        signAlgorithm(alg),
+        key,
+        encoder.encode(`${protectedB64}.${payloadB64}`),
+      );
+      return {
+        protected: protectedB64,
+        payload: payloadB64,
+        signature: base64url(signature),
+      };
+    },
+    catch: (cause) =>
+      new JoseError({ message: "Signing the ACME request failed.", cause }),
+  });
+
+/**
+ * The External Account Binding JWS (RFC 8555 §7.3.4): HS256 over the
+ * account's public JWK, keyed by the CA-issued HMAC key, with the CA's key
+ * id as `kid`.
+ */
+export const signExternalAccountBinding = (options: {
+  readonly jwk: Jwk;
+  readonly url: string;
+  readonly keyId: string;
+  readonly hmacKey: Redacted.Redacted<string> | string;
+}): Effect.Effect<FlattenedJws, JoseError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const raw = Redacted.isRedacted(options.hmacKey)
+        ? Redacted.value(options.hmacKey)
+        : options.hmacKey;
+      const key = await crypto.subtle.importKey(
+        "raw",
+        base64urlDecode(raw) as Uint8Array<ArrayBuffer>,
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+      );
+      const protectedB64 = base64urlJson({
+        alg: "HS256",
+        kid: options.keyId,
+        url: options.url,
+      });
+      const payloadB64 = base64urlJson(publicJwk(options.jwk));
+      const signature = await crypto.subtle.sign(
+        "HMAC",
+        key,
+        encoder.encode(`${protectedB64}.${payloadB64}`),
+      );
+      return {
+        protected: protectedB64,
+        payload: payloadB64,
+        signature: base64url(signature),
+      };
+    },
+    catch: (cause) =>
+      new JoseError({
+        message: "Signing the External Account Binding failed.",
+        cause,
+      }),
+  });