@composurecdk/acm 0.3.2

package/README.md

@@ -0,0 +1,144 @@
+# @composurecdk/acm
+
+AWS Certificate Manager builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for ACM certificates with secure, AWS-recommended defaults, first-class DNS validation wiring, and a recommended `DaysToExpiry` alarm. It wraps the CDK [Certificate](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_certificatemanager.Certificate.html) construct — refer to the CDK documentation for the full set of configurable properties.
+
+## Certificate Builder
+
+```ts
+import { createCertificateBuilder } from "@composurecdk/acm";
+import { HostedZone } from "aws-cdk-lib/aws-route53";
+
+const zone = HostedZone.fromLookup(stack, "Zone", { domainName: "example.com" });
+
+const { certificate } = createCertificateBuilder()
+  .domainName("example.com")
+  .subjectAlternativeNames(["www.example.com"])
+  .validationZone(zone)
+  .build(stack, "SiteCert");
+```
+
+Every [CertificateProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_certificatemanager.CertificateProps.html) property is available as a fluent setter on the builder.
+
+## Secure Defaults
+
+`createCertificateBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property                     | Default                 | Rationale                                                                     |
+| ---------------------------- | ----------------------- | ----------------------------------------------------------------------------- |
+| `keyAlgorithm`               | `KeyAlgorithm.RSA_2048` | Broadest client and AWS service compatibility (CloudFront, API Gateway, ALB). |
+| `transparencyLoggingEnabled` | `true`                  | Required by modern browsers; enables public detection of mis-issuance.        |
+
+These defaults are guided by the [AWS ACM Best Practices](https://docs.aws.amazon.com/acm/latest/userguide/acm-bestpractices.html).
+
+The defaults are exported as `CERTIFICATE_DEFAULTS` for visibility and testing:
+
+```ts
+import { CERTIFICATE_DEFAULTS } from "@composurecdk/acm";
+```
+
+## DNS Validation
+
+Email-based validation is not used by default — it blocks stack creation until a human clicks a link in an email. The builder requires one of:
+
+- `validationZone(zone)` — the hosted zone that owns every domain on the certificate.
+- `validationZones({ "apex.com": apexZone, "alt.net": altZone })` — when domains span multiple zones.
+- `validation(CertificateValidation.fromEmail())` — explicit opt-in to email validation (not recommended).
+
+`validationZone` / `validationZones` accept a `Resolvable<IHostedZone>`, so a hosted zone produced by a sibling component can be wired via `ref()`.
+
+## Certificate Lifetime
+
+ACM-issued public certificates are valid for [395 days](https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate.html) and auto-renew starting ~60 days before expiry, provided the DNS validation records remain published. Renewal is therefore the happy path — the `daysToExpiry` alarm below is a safety net for the cases where it can't complete (records removed, zone delegation broken, etc.). For imported certificates, which do not auto-renew, `daysToExpiry` is the primary expiry control.
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm          | Metric                        | Default threshold |
+| -------------- | ----------------------------- | ----------------- |
+| `daysToExpiry` | DaysToExpiry (Minimum, 1 day) | ≤ 45 days         |
+
+`treatMissingData` defaults to `notBreaching`: once a certificate has effectively expired, ACM stops emitting `DaysToExpiry`, and there is nothing left to alarm about.
+
+The defaults are exported as `CERTIFICATE_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { CERTIFICATE_ALARM_DEFAULTS } from "@composurecdk/acm";
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const cert = createCertificateBuilder()
+  .domainName("example.com")
+  .validationZone(zone)
+  .recommendedAlarms({
+    daysToExpiry: { threshold: 30 },
+  });
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable the daysToExpiry alarm individually:
+
+```ts
+builder.recommendedAlarms({ daysToExpiry: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `ICertificate`, so the metric factory has access to the certificate at build time.
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+import { Duration } from "aws-cdk-lib";
+
+const cert = createCertificateBuilder()
+  .domainName("example.com")
+  .validationZone(zone)
+  .addAlarm("urgentExpiry", (alarm) =>
+    alarm
+      .metric(
+        (c) =>
+          new Metric({
+            namespace: "AWS/CertificateManager",
+            metricName: "DaysToExpiry",
+            dimensionsMap: { CertificateArn: c.certificateArn },
+            statistic: "Minimum",
+            period: Duration.days(1),
+          }),
+      )
+      .threshold(10)
+      .lessThanOrEqual()
+      .description("Certificate very close to expiry — page oncall"),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = cert.build(stack, "SiteCert");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+## CloudFront certificates
+
+CloudFront viewer certificates must live in `us-east-1`. The ACM builder cannot enforce this on its own — certificates in other regions are perfectly valid for ALB, API Gateway, and other services. The constraint is enforced by CloudFront at association time, so if your certificate is for CloudFront, place the builder in a stack that targets `us-east-1` (e.g. via [`createStackBuilder`](../cloudformation/README.md) with an `env`).

package/dist/alarm-config.d.ts

@@ -0,0 +1,34 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an ACM certificate.
+ * All applicable alarms are enabled by default with AWS-recommended thresholds.
+ * Set individual alarms to `false` to disable them, or provide an
+ * {@link AlarmConfig} to tune thresholds.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+ */
+export interface CertificateAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm when the certificate is approaching expiry.
+     *
+     * ACM public certificates auto-renew, so this alarm is primarily a
+     * safety net for the edge cases where renewal cannot complete (for
+     * example, when DNS validation records have been removed from the
+     * zone). For imported certificates, which do not auto-renew, this
+     * alarm is the primary expiry control.
+     *
+     * Metric: `AWS/CertificateManager DaysToExpiry`, statistic Minimum,
+     * period 1 day, dimension `CertificateArn`.
+     * Default threshold: ≤ 45 days.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+     */
+    daysToExpiry?: AlarmConfig | false;
+}
+//# sourceMappingURL=alarm-config.d.ts.map

package/dist/alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.d.ts","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CACpC"}

package/dist/alarm-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alarm-config.js.map

package/dist/alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-config.js","sourceRoot":"","sources":["../src/alarm-config.ts"],"names":[],"mappings":""}

package/dist/alarm-defaults.d.ts

@@ -0,0 +1,13 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+interface CertificateAlarmDefaults {
+    enabled: true;
+    daysToExpiry: Required<AlarmConfig>;
+}
+/**
+ * AWS-recommended default alarm configuration for ACM certificates.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+ */
+export declare const CERTIFICATE_ALARM_DEFAULTS: CertificateAlarmDefaults;
+export {};
+//# sourceMappingURL=alarm-defaults.d.ts.map

package/dist/alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.d.ts","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,UAAU,wBAAwB;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,wBAmBxC,CAAC"}

package/dist/alarm-defaults.js

@@ -0,0 +1,26 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for ACM certificates.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+ */
+export const CERTIFICATE_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * Alarm 45 days before expiry — AWS's recommended threshold. For public
+     * certificates, ACM begins auto-renewal attempts around 60 days out, so
+     * 45 days leaves a two-week window to investigate renewal failures
+     * before the certificate expires.
+     *
+     * `treatMissingData: notBreaching` avoids false alarms after a
+     * certificate has effectively expired — at that point ACM stops
+     * emitting DaysToExpiry, and there is nothing left to alarm about.
+     */
+    daysToExpiry: {
+        threshold: 45,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=alarm-defaults.js.map

package/dist/alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm-defaults.js","sourceRoot":"","sources":["../src/alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAQ9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAA6B;IAClE,OAAO,EAAE,IAAI;IAEb;;;;;;;;;OASG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/certificate-alarms.d.ts

@@ -0,0 +1,26 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { CertificateAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an ACM certificate.
+ */
+export declare function resolveCertificateAlarmDefinitions(certificate: ICertificate, config: CertificateAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an ACM certificate,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param certificate - The ACM certificate to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+ */
+export declare function createCertificateAlarms(scope: IConstruct, id: string, certificate: ICertificate, config: CertificateAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<ICertificate>[]): Record<string, Alarm>;
+//# sourceMappingURL=certificate-alarms.d.ts.map

package/dist/certificate-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate-alarms.d.ts","sourceRoot":"","sources":["../src/certificate-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAsB,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAKhE;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,YAAY,EACzB,MAAM,EAAE,sBAAsB,GAAG,SAAS,GACzC,eAAe,EAAE,CAoBnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,YAAY,EACzB,MAAM,EAAE,sBAAsB,GAAG,KAAK,GAAG,SAAS,EAClD,YAAY,GAAE,sBAAsB,CAAC,YAAY,CAAC,EAAO,GACxD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/certificate-alarms.js

@@ -0,0 +1,52 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { CERTIFICATE_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = Duration.days(1);
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an ACM certificate.
+ */
+export function resolveCertificateAlarmDefinitions(certificate, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.daysToExpiry !== false) {
+        const cfg = resolveAlarmConfig(config?.daysToExpiry, CERTIFICATE_ALARM_DEFAULTS.daysToExpiry);
+        definitions.push({
+            key: "daysToExpiry",
+            metric: certificate.metricDaysToExpiry({ period: METRIC_PERIOD }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.LESS_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `ACM certificate is approaching expiry. Threshold: <= ${String(cfg.threshold)} days remaining.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an ACM certificate,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param certificate - The ACM certificate to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+ */
+export function createCertificateAlarms(scope, id, certificate, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? CERTIFICATE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveCertificateAlarmDefinitions(certificate, config);
+    const custom = customAlarms.map((b) => b.resolve(certificate));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=certificate-alarms.js.map

package/dist/certificate-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate-alarms.js","sourceRoot":"","sources":["../src/certificate-alarms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAc,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAI5E,OAAO,EAA0B,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,kCAAkC,CAChD,WAAyB,EACzB,MAA0C;IAE1C,IAAI,MAAM,EAAE,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAsB,EAAE,CAAC;IAE1C,IAAI,MAAM,EAAE,YAAY,KAAK,KAAK,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,0BAA0B,CAAC,YAAY,CAAC,CAAC;QAC9F,WAAW,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,cAAc;YACnB,MAAM,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YACjE,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,kBAAkB,EAAE,kBAAkB,CAAC,+BAA+B;YACtE,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;YACxC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACtC,WAAW,EAAE,wDAAwD,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,kBAAkB;SAC7G,CAAC,CAAC;IACL,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAiB,EACjB,EAAU,EACV,WAAyB,EACzB,MAAkD,EAClD,eAAuD,EAAE;IAEzD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,0BAA0B,CAAC,OAAO,CAAC;IACtE,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,MAAM,WAAW,GAAG,kCAAkC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAE/D,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC"}

package/dist/certificate-builder.d.ts

@@ -0,0 +1,136 @@
+import { Certificate, type CertificateProps, type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IHostedZone } from "aws-cdk-lib/aws-route53";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { CertificateAlarmConfig } from "./alarm-config.js";
+/**
+ * Configuration properties for the ACM certificate builder.
+ *
+ * Extends the CDK {@link CertificateProps} with additional builder-specific
+ * options. The `validation` field is augmented by {@link validationZone} /
+ * {@link validationZones}, which accept {@link Resolvable} hosted zones so
+ * the validation zone can come from a composed component.
+ *
+ * If neither `validation`, `validationZone`, nor `validationZones` is set,
+ * the builder fails fast — falling back to ACM's email-based validation would
+ * stall stack creation waiting on a human to click a link.
+ */
+interface CertificateBuilderProps extends CertificateProps {
+    /**
+     * The hosted zone used to automatically create DNS validation records
+     * for every domain on the certificate. Accepts a {@link Resolvable} so
+     * a zone produced by a sibling component can be wired in via `ref`.
+     *
+     * Mutually exclusive with {@link validationZones} and {@link CertificateProps.validation}.
+     * When set, the builder configures
+     * {@link CertificateValidation.fromDns | CertificateValidation.fromDns(zone)}.
+     */
+    validationZone?: Resolvable<IHostedZone>;
+    /**
+     * A map of domain name to hosted zone, used when the apex and subject
+     * alternative names live in different zones. Each value accepts a
+     * {@link Resolvable}. When set, the builder configures
+     * {@link CertificateValidation.fromDnsMultiZone}.
+     *
+     * Mutually exclusive with {@link validationZone} and {@link CertificateProps.validation}.
+     */
+    validationZones?: Record<string, Resolvable<IHostedZone>>;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates a recommended `daysToExpiry` alarm
+     * at 45 days. The alarm can be customized or disabled. Set to `false`
+     * to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification
+     * methods are user-specific. Access alarms from the build result
+     * or use an `afterBuild` hook to apply actions.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+     */
+    recommendedAlarms?: CertificateAlarmConfig | false;
+}
+/**
+ * The build output of an {@link ICertificateBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface CertificateBuilderResult {
+    /** The ACM certificate construct created by the builder. */
+    certificate: Certificate;
+    /**
+     * CloudWatch alarms created for the certificate, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link ICertificateBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.daysToExpiry`).
+     *
+     * No alarm actions are configured — apply them via the result or an
+     * `afterBuild` hook.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#CertificateManager
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS Certificate Manager
+ * certificate.
+ *
+ * Each configuration property from the CDK {@link CertificateProps} is
+ * exposed as an overloaded method: call with a value to set it (returns the
+ * builder for chaining), or call with no arguments to read the current value.
+ *
+ * Validation is DNS-based by default — set
+ * {@link CertificateBuilderProps.validationZone | validationZone} (or
+ * {@link CertificateBuilderProps.validationZones | validationZones}) with the
+ * hosted zone(s) that own the certificate's domains. Accepts a
+ * {@link Resolvable} so zones produced by a composed component can be
+ * wired in via `ref`.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * an ACM certificate with the configured properties and returns a
+ * {@link CertificateBuilderResult}.
+ *
+ * The builder also creates AWS-recommended CloudWatch alarms by default
+ * (`daysToExpiry` at 45 days). Alarms can be customized or disabled via the
+ * `recommendedAlarms` property.
+ *
+ * @example
+ * ```ts
+ * const cert = createCertificateBuilder()
+ *   .domainName("example.com")
+ *   .subjectAlternativeNames(["www.example.com"])
+ *   .validationZone(zone);
+ * ```
+ */
+export type ICertificateBuilder = IBuilder<CertificateBuilderProps, CertificateBuilder>;
+declare class CertificateBuilder implements Lifecycle<CertificateBuilderResult> {
+    props: Partial<CertificateBuilderProps>;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<ICertificate>) => AlarmDefinitionBuilder<ICertificate>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): CertificateBuilderResult;
+}
+/**
+ * Creates a new {@link ICertificateBuilder} for configuring an ACM certificate.
+ *
+ * This is the entry point for defining an ACM certificate component. The
+ * returned builder exposes every {@link CertificateBuilderProps} property as
+ * a fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @returns A fluent builder for an ACM certificate.
+ *
+ * @example
+ * ```ts
+ * const cert = createCertificateBuilder()
+ *   .domainName("example.com")
+ *   .validationZone(zone);
+ *
+ * const result = cert.build(stack, "SiteCert");
+ * ```
+ */
+export declare function createCertificateBuilder(): ICertificateBuilder;
+export {};
+//# sourceMappingURL=certificate-builder.d.ts.map

package/dist/certificate-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate-builder.d.ts","sourceRoot":"","sources":["../src/certificate-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EAEX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAIhE;;;;;;;;;;;GAWG;AACH,UAAU,uBAAwB,SAAQ,gBAAgB;IACxD;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAEzC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAE1D;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,WAAW,EAAE,WAAW,CAAC;IAEzB;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;AAExF,cAAM,kBAAmB,YAAW,SAAS,CAAC,wBAAwB,CAAC;IACrE,KAAK,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAM;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8C;IAE3E,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CACT,KAAK,EAAE,sBAAsB,CAAC,YAAY,CAAC,KACxC,sBAAsB,CAAC,YAAY,CAAC,GACxC,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,wBAAwB;CA4DjG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,IAAI,mBAAmB,CAE9D"}

package/dist/certificate-builder.js

@@ -0,0 +1,77 @@
+import { Certificate, CertificateValidation, } from "aws-cdk-lib/aws-certificatemanager";
+import { Builder, resolve, } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createCertificateAlarms } from "./certificate-alarms.js";
+import { CERTIFICATE_DEFAULTS } from "./defaults.js";
+class CertificateBuilder {
+    props = {};
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    build(scope, id, context) {
+        const { validationZone, validationZones, validation: userValidation, recommendedAlarms: alarmConfig, ...certProps } = this.props;
+        if (!certProps.domainName) {
+            throw new Error(`CertificateBuilder "${id}" requires a domainName. ` +
+                `Call .domainName() with the fully-qualified domain.`);
+        }
+        if ([userValidation, validationZone, validationZones].filter(Boolean).length > 1) {
+            throw new Error(`CertificateBuilder "${id}": 'validation', 'validationZone', and 'validationZones' ` +
+                `are mutually exclusive. Set exactly one.`);
+        }
+        const resolvedContext = context ?? {};
+        let validation;
+        if (userValidation) {
+            validation = userValidation;
+        }
+        else if (validationZones) {
+            const resolvedZones = Object.fromEntries(Object.entries(validationZones).map(([domain, zone]) => [
+                domain,
+                resolve(zone, resolvedContext),
+            ]));
+            validation = CertificateValidation.fromDnsMultiZone(resolvedZones);
+        }
+        else if (validationZone) {
+            validation = CertificateValidation.fromDns(resolve(validationZone, resolvedContext));
+        }
+        else {
+            throw new Error(`CertificateBuilder "${id}" requires DNS validation to be configured. ` +
+                `Call .validationZone() with the hosted zone for the certificate's domain, ` +
+                `or .validationZones() when domains span multiple zones, ` +
+                `or .validation() to configure an explicit CertificateValidation. ` +
+                `Email validation is not enabled by default because it blocks stack creation.`);
+        }
+        const mergedProps = {
+            ...CERTIFICATE_DEFAULTS,
+            ...certProps,
+            validation,
+        };
+        const certificate = new Certificate(scope, id, mergedProps);
+        const alarms = createCertificateAlarms(scope, id, certificate, alarmConfig, this.customAlarms);
+        return { certificate, alarms };
+    }
+}
+/**
+ * Creates a new {@link ICertificateBuilder} for configuring an ACM certificate.
+ *
+ * This is the entry point for defining an ACM certificate component. The
+ * returned builder exposes every {@link CertificateBuilderProps} property as
+ * a fluent setter/getter and implements {@link Lifecycle} for use with
+ * {@link compose}.
+ *
+ * @returns A fluent builder for an ACM certificate.
+ *
+ * @example
+ * ```ts
+ * const cert = createCertificateBuilder()
+ *   .domainName("example.com")
+ *   .validationZone(zone);
+ *
+ * const result = cert.build(stack, "SiteCert");
+ * ```
+ */
+export function createCertificateBuilder() {
+    return Builder(CertificateBuilder);
+}
+//# sourceMappingURL=certificate-builder.js.map

package/dist/certificate-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificate-builder.js","sourceRoot":"","sources":["../src/certificate-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,GAGtB,MAAM,oCAAoC,CAAC;AAI5C,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA6GrD,MAAM,kBAAkB;IACtB,KAAK,GAAqC,EAAE,CAAC;IAC5B,YAAY,GAA2C,EAAE,CAAC;IAE3E,QAAQ,CACN,GAAW,EACX,SAEyC;QAEzC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,sBAAsB,CAAe,GAAG,CAAC,CAAC,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAiB,EAAE,EAAU,EAAE,OAAgC;QACnE,MAAM,EACJ,cAAc,EACd,eAAe,EACf,UAAU,EAAE,cAAc,EAC1B,iBAAiB,EAAE,WAAW,EAC9B,GAAG,SAAS,EACb,GAAG,IAAI,CAAC,KAAK,CAAC;QAEf,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,2BAA2B;gBAClD,qDAAqD,CACxD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,cAAc,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,2DAA2D;gBAClF,0CAA0C,CAC7C,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,IAAI,EAAE,CAAC;QACtC,IAAI,UAAiC,CAAC;QAEtC,IAAI,cAAc,EAAE,CAAC;YACnB,UAAU,GAAG,cAAc,CAAC;QAC9B,CAAC;aAAM,IAAI,eAAe,EAAE,CAAC;YAC3B,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;gBACtD,MAAM;gBACN,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC;aAC/B,CAAC,CACH,CAAC;YACF,UAAU,GAAG,qBAAqB,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;QACrE,CAAC;aAAM,IAAI,cAAc,EAAE,CAAC;YAC1B,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;QACvF,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,uBAAuB,EAAE,8CAA8C;gBACrE,4EAA4E;gBAC5E,0DAA0D;gBAC1D,mEAAmE;gBACnE,8EAA8E,CACjF,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,oBAAoB;YACvB,GAAG,SAAS;YACZ,UAAU;SACS,CAAC;QAEtB,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC;QAE5D,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAE/F,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAA8C,kBAAkB,CAAC,CAAC;AAClF,CAAC"}

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import { type CertificateProps } from "aws-cdk-lib/aws-certificatemanager";
+/**
+ * Secure, AWS-recommended defaults applied to every ACM certificate built
+ * with {@link createCertificateBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export declare const CERTIFICATE_DEFAULTS: Partial<CertificateProps>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,CAAC,gBAAgB,CAiB1D,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,24 @@
+import { KeyAlgorithm } from "aws-cdk-lib/aws-certificatemanager";
+/**
+ * Secure, AWS-recommended defaults applied to every ACM certificate built
+ * with {@link createCertificateBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ */
+export const CERTIFICATE_DEFAULTS = {
+    /**
+     * Use RSA-2048 as the key algorithm. Widest client/CDN compatibility
+     * (CloudFront, API Gateway, ALB) and sufficient for TLS 1.2 and 1.3.
+     * For newer workloads, `KeyAlgorithm.EC_PRIME256V1` offers smaller
+     * signatures at comparable security — override via `.keyAlgorithm()`.
+     * @see https://docs.aws.amazon.com/acm/latest/userguide/acm-certificate.html#algorithms.title
+     */
+    keyAlgorithm: KeyAlgorithm.RSA_2048,
+    /**
+     * Publish certificates to the public Certificate Transparency (CT) logs.
+     * CT logging is required by modern browsers to trust a certificate and
+     * enables detection of mis-issuance.
+     * @see https://docs.aws.amazon.com/acm/latest/userguide/acm-bestpractices.html#best-practices-transparency
+     */
+    transparencyLoggingEnabled: true,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyB,MAAM,oCAAoC,CAAC;AAEzF;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA8B;IAC7D;;;;;;OAMG;IACH,YAAY,EAAE,YAAY,CAAC,QAAQ;IAEnC;;;;;OAKG;IACH,0BAA0B,EAAE,IAAI;CACjC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createCertificateBuilder, type CertificateBuilderResult, type ICertificateBuilder, } from "./certificate-builder.js";
+export { CERTIFICATE_DEFAULTS } from "./defaults.js";
+export { type CertificateAlarmConfig } from "./alarm-config.js";
+export { CERTIFICATE_ALARM_DEFAULTS } from "./alarm-defaults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createCertificateBuilder, } from "./certificate-builder.js";
+export { CERTIFICATE_DEFAULTS } from "./defaults.js";
+export { CERTIFICATE_ALARM_DEFAULTS } from "./alarm-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAGzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@composurecdk/acm",
+  "version": "0.3.2",
+  "description": "Composable AWS Certificate Manager builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/acm"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/cloudwatch": "^0.3.0",
+    "@composurecdk/core": "^0.3.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "aws-cdk-lib": "^2.250.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  }
+}