@composurecdk/s3 0.1.3 → 0.3.2

package/README.md

@@ -0,0 +1,226 @@
+# @composurecdk/s3
+
+S3 builders for [ComposureCDK](../../README.md).
+
+This package provides fluent builders for S3 buckets and bucket deployments with secure, AWS-recommended defaults. It wraps the CDK [Bucket](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html) and [BucketDeployment](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html) constructs — refer to the CDK documentation for the full set of configurable properties.
+
+## Bucket Builder
+
+```ts
+import { createBucketBuilder } from "@composurecdk/s3";
+
+const site = createBucketBuilder().bucketName("my-website-bucket").build(stack, "SiteBucket");
+```
+
+Every [BucketProps](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html) property is available as a fluent setter on the builder.
+
+### Secure Defaults
+
+`createBucketBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property            | Default      | Rationale                                                        |
+| ------------------- | ------------ | ---------------------------------------------------------------- |
+| `accessLogging`     | `true`       | Auto-creates a logging bucket for server access log audit trail. |
+| `accessLogsPrefix`  | `"logs/"`    | Default prefix for access log object keys.                       |
+| `blockPublicAccess` | `BLOCK_ALL`  | Prevents public access unless explicitly required.               |
+| `encryption`        | `S3_MANAGED` | Enables server-side encryption with S3-managed keys (SSE-S3).    |
+| `enforceSSL`        | `true`       | Requires SSL/TLS for all requests to the bucket.                 |
+| `versioned`         | `true`       | Protects against accidental deletions and supports rollback.     |
+| `removalPolicy`     | `RETAIN`     | Retains the bucket on stack deletion to prevent data loss.       |
+
+These defaults are guided by the [AWS Well-Architected Security Pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html).
+
+The defaults are exported as `BUCKET_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_DEFAULTS } from "@composurecdk/s3";
+```
+
+### Overriding defaults
+
+```ts
+import { RemovalPolicy } from "aws-cdk-lib";
+import { BlockPublicAccess } from "aws-cdk-lib/aws-s3";
+
+const bucket = createBucketBuilder()
+  .blockPublicAccess(BlockPublicAccess.BLOCK_ACLS)
+  .versioned(false)
+  .removalPolicy(RemovalPolicy.DESTROY)
+  .build(stack, "MyBucket");
+```
+
+When `removalPolicy` is set to `DESTROY`, the builder automatically enables `autoDeleteObjects` (unless explicitly set to `false`) so that non-empty buckets can be cleanly removed during stack deletion.
+
+### Access logging
+
+By default, the builder creates a dedicated logging bucket with secure defaults and configures it as the server access logs destination. The created bucket is returned in the build result:
+
+```ts
+const result = createBucketBuilder().build(stack, "MyBucket");
+
+result.bucket; // Bucket
+result.accessLogsBucket; // Bucket | undefined
+```
+
+To provide your own destination instead, set `serverAccessLogsBucket` — the auto-created logging bucket is skipped. To disable access logging entirely, set `.accessLogging(false)`.
+
+## Recommended Alarms
+
+The builder creates [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3) automatically when [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html) are configured on the bucket via `.metrics()`. One alarm per metric is created for each metrics configuration entry. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm          | Metric                 | Default threshold | Created when               |
+| -------------- | ---------------------- | ----------------- | -------------------------- |
+| `serverErrors` | 5xxErrors (Sum, 5 min) | > 0               | `.metrics()` is configured |
+| `clientErrors` | 4xxErrors (Sum, 5 min) | > 0               | `.metrics()` is configured |
+
+Alarm keys include the metrics filter ID (e.g. `serverErrors:EntireBucket`). When multiple metrics configurations are provided, alarms are created for each one.
+
+The defaults are exported as `BUCKET_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_ALARM_DEFAULTS } from "@composurecdk/s3";
+```
+
+### Enabling alarms
+
+Configure request metrics on the bucket — alarms are created automatically:
+
+```ts
+const site = createBucketBuilder().metrics([{ id: "EntireBucket" }]);
+```
+
+### Multiple metrics configurations
+
+Alarms are created for each metrics configuration entry:
+
+```ts
+const site = createBucketBuilder().metrics([
+  { id: "EntireBucket" },
+  { id: "UploadsOnly", prefix: "uploads/" },
+]);
+
+// Creates: serverErrors:EntireBucket, clientErrors:EntireBucket,
+//          serverErrors:UploadsOnly, clientErrors:UploadsOnly
+```
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+builder.metrics([{ id: "EntireBucket" }]).recommendedAlarms({
+  serverErrors: { threshold: 5, evaluationPeriods: 3 },
+  clientErrors: { threshold: 50 },
+});
+```
+
+### Disabling alarms
+
+Disable all recommended alarms:
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+```
+
+Disable individual alarms:
+
+```ts
+builder.metrics([{ id: "EntireBucket" }]).recommendedAlarms({ clientErrors: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to the S3 `Bucket`, so the metric factory has access to the bucket's metric helpers.
+
+```ts
+import { Metric } from "aws-cdk-lib/aws-cloudwatch";
+
+const site = createBucketBuilder()
+  .metrics([{ id: "EntireBucket" }])
+  .addAlarm("lowTraffic", (alarm) =>
+    alarm
+      .metric(
+        (bucket) =>
+          new Metric({
+            namespace: "AWS/S3",
+            metricName: "GetRequests",
+            dimensionsMap: {
+              BucketName: bucket.bucketName,
+              FilterId: "EntireBucket",
+            },
+            period: Duration.minutes(5),
+          }),
+      )
+      .threshold(10)
+      .lessThan()
+      .description("Bucket traffic has dropped below expected level"),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = site.build(stack, "SiteBucket");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+## Bucket Deployment Builder
+
+Deploys local assets to an S3 bucket with optional CloudFront cache invalidation.
+
+```ts
+import { createBucketDeploymentBuilder } from "@composurecdk/s3";
+import { Source } from "aws-cdk-lib/aws-s3-deployment";
+
+const deploy = createBucketDeploymentBuilder()
+  .sources([Source.asset("./site")])
+  .destinationBucket(myBucket)
+  .build(stack, "Deploy");
+```
+
+The `destinationBucket` and `distribution` methods accept `Ref` values for cross-component wiring:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+
+const deploy = createBucketDeploymentBuilder()
+  .sources([Source.asset("./site")])
+  .destinationBucket(ref("site", (r) => r.bucket))
+  .distribution(ref("cdn", (r) => r.distribution));
+
+compose(
+  { site: createBucketBuilder(), cdn: createDistributionBuilder(), deploy },
+  { site: [], cdn: ["site"], deploy: ["site", "cdn"] },
+).build(stack, "Website");
+```
+
+### Secure Defaults
+
+`createBucketDeploymentBuilder` applies the following defaults. Each can be overridden via the builder's fluent API.
+
+| Property            | Default  | Rationale                                                                                                           |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `prune`             | `true`   | Removes stale files from the destination, keeping it in sync with the source.                                       |
+| `memoryLimit`       | `256`    | Allocates 256 MiB to the deployment Lambda (CDK default of 128 MiB is insufficient for larger deployments).         |
+| `retainOnDelete`    | `false`  | Does not retain deployed files on stack deletion, consistent with prune semantics.                                  |
+| `distributionPaths` | `["/*"]` | Invalidates all CloudFront paths so content is immediately visible. Only applied when a distribution is configured. |
+
+The builder also auto-creates a managed CloudWatch LogGroup (using `@composurecdk/logs` with its secure defaults) for the deployment's backing Lambda, preventing the auto-created log group with infinite retention.
+
+The defaults are exported as `BUCKET_DEPLOYMENT_DEFAULTS` for visibility and testing:
+
+```ts
+import { BUCKET_DEPLOYMENT_DEFAULTS } from "@composurecdk/s3";
+```
+
+## Examples
+
+- [StaticWebsiteStack](../examples/src/static-website/app.ts) — S3 + CloudFront static website with OAC, error pages, and content deployment

package/dist/alarm-config.d.ts

@@ -0,0 +1,48 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for an S3 bucket.
+ * 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.
+ *
+ * S3 request metric alarms (5xxErrors, 4xxErrors) require
+ * [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html)
+ * to be enabled on the bucket. Alarms are automatically created for each
+ * entry in the bucket's {@link BucketProps.metrics} array, keyed by the
+ * metrics configuration ID (e.g. `serverErrors:EntireBucket`).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export interface BucketAlarmConfig {
+    /**
+     * 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 S3 returns server-side errors (5xx HTTP status codes).
+     *
+     * Metric: `AWS/S3 5xxErrors`, statistic Sum, period 5 minutes.
+     * Default threshold: > 0 errors.
+     *
+     * Only created when the bucket has request metrics configured via
+     * {@link BucketProps.metrics}. One alarm per metrics configuration.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    serverErrors?: AlarmConfig | false;
+    /**
+     * Alarm when S3 returns client-side errors (4xx HTTP status codes).
+     *
+     * Metric: `AWS/S3 4xxErrors`, statistic Sum, period 5 minutes.
+     * Default threshold: > 0 errors.
+     *
+     * Only created when the bucket has request metrics configured via
+     * {@link BucketProps.metrics}. One alarm per metrics configuration.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+     */
+    clientErrors?: 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;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnC;;;;;;;;;;OAUG;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,14 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+interface BucketAlarmDefaults {
+    enabled: true;
+    serverErrors: Required<AlarmConfig>;
+    clientErrors: Required<AlarmConfig>;
+}
+/**
+ * AWS-recommended default alarm configuration for S3 buckets.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export declare const BUCKET_ALARM_DEFAULTS: BucketAlarmDefaults;
+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,mBAAmB;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAkBnC,CAAC"}

package/dist/alarm-defaults.js

@@ -0,0 +1,24 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for S3 buckets.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#S3
+ */
+export const BUCKET_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Any server-side error is worth investigating; threshold 0. */
+    serverErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Any client-side error pattern is worth investigating; threshold 0. */
+    clientErrors: {
+        threshold: 0,
+        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;AAS9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACxD,OAAO,EAAE,IAAI;IAEb,iEAAiE;IACjE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,yEAAyE;IACzE,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/bucket-alarms.d.ts

@@ -0,0 +1,34 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { Bucket, BucketMetrics } from "aws-cdk-lib/aws-s3";
+import type { IConstruct } from "constructs";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import type { BucketAlarmConfig } from "./alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an S3 bucket.
+ *
+ * Creates alarms for each entry in `metricsConfigs`, keyed as
+ * `{alarmType}:{filterId}` (e.g. `serverErrors:EntireBucket`).
+ */
+export declare function resolveBucketAlarmDefinitions(bucket: Bucket, config: BucketAlarmConfig | undefined, metricsConfigs: BucketMetrics[]): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for an S3 bucket,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * Alarms are created for each entry in `metricsConfigs` (from
+ * {@link BucketProps.metrics}). If no metrics configurations are
+ * provided, only custom alarms are created.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param bucket - The S3 bucket to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param metricsConfigs - The bucket's request metrics configurations.
+ * @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#S3
+ */
+export declare function createBucketAlarms(scope: IConstruct, id: string, bucket: Bucket, config: BucketAlarmConfig | false | undefined, metricsConfigs: BucketMetrics[], customAlarms?: AlarmDefinitionBuilder<Bucket>[]): Record<string, Alarm>;
+//# sourceMappingURL=bucket-alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-alarms.d.ts","sourceRoot":"","sources":["../src/bucket-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAqC,MAAM,4BAA4B,CAAC;AAC3F,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA2B3D;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,cAAc,EAAE,aAAa,EAAE,GAC9B,eAAe,EAAE,CAuCnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/bucket-alarms.js

@@ -0,0 +1,94 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(5);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minutes`;
+/**
+ * Creates an S3 request metric with the correct namespace and dimensions.
+ */
+function s3RequestMetric(bucket, filterId, metricName, statistic) {
+    return new Metric({
+        namespace: "AWS/S3",
+        metricName,
+        dimensionsMap: {
+            BucketName: bucket.bucketName,
+            FilterId: filterId,
+        },
+        statistic,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for an S3 bucket.
+ *
+ * Creates alarms for each entry in `metricsConfigs`, keyed as
+ * `{alarmType}:{filterId}` (e.g. `serverErrors:EntireBucket`).
+ */
+export function resolveBucketAlarmDefinitions(bucket, config, metricsConfigs) {
+    if (config?.enabled === false)
+        return [];
+    if (metricsConfigs.length === 0)
+        return [];
+    const definitions = [];
+    for (const metrics of metricsConfigs) {
+        const filterId = metrics.id;
+        if (config?.serverErrors !== false) {
+            const cfg = resolveAlarmConfig(config?.serverErrors, BUCKET_ALARM_DEFAULTS.serverErrors);
+            definitions.push({
+                key: `serverErrors:${filterId}`,
+                metric: s3RequestMetric(bucket, filterId, "5xxErrors", Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning server-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 5xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+        if (config?.clientErrors !== false) {
+            const cfg = resolveAlarmConfig(config?.clientErrors, BUCKET_ALARM_DEFAULTS.clientErrors);
+            definitions.push({
+                key: `clientErrors:${filterId}`,
+                metric: s3RequestMetric(bucket, filterId, "4xxErrors", Stats.SUM),
+                threshold: cfg.threshold,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                evaluationPeriods: cfg.evaluationPeriods,
+                datapointsToAlarm: cfg.datapointsToAlarm,
+                treatMissingData: cfg.treatMissingData,
+                description: `S3 bucket is returning client-side errors (filter: ${filterId}). Threshold: > ${String(cfg.threshold)} 4xx errors in ${METRIC_PERIOD_LABEL}.`,
+            });
+        }
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for an S3 bucket,
+ * merging recommended definitions with any custom alarm builders.
+ *
+ * Alarms are created for each entry in `metricsConfigs` (from
+ * {@link BucketProps.metrics}). If no metrics configurations are
+ * provided, only custom alarms are created.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param bucket - The S3 bucket to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param metricsConfigs - The bucket's request metrics configurations.
+ * @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#S3
+ */
+export function createBucketAlarms(scope, id, bucket, config, metricsConfigs, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? BUCKET_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveBucketAlarmDefinitions(bucket, config, metricsConfigs);
+    const custom = customAlarms.map((b) => b.resolve(bucket));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=bucket-alarms.js.map

package/dist/bucket-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket-alarms.js","sourceRoot":"","sources":["../src/bucket-alarms.ts"],"names":[],"mappings":"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"}

package/dist/bucket-builder.d.ts

@@ -1,6 +1,9 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { Bucket, type BucketProps } from "aws-cdk-lib/aws-s3";
 import { type IConstruct } from "constructs";
 import { type IBuilder, type Lifecycle } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { BucketAlarmConfig } from "./alarm-config.js";
 /**
  * Configuration properties for the S3 bucket builder.
  *
@@ -35,6 +38,21 @@ export interface BucketBuilderProps extends BucketProps {
      * @default "logs/"
      */
     accessLogsPrefix?: string;
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * S3 request metric alarms (5xxErrors, 4xxErrors) require
+     * [CloudWatch request metrics](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configure-request-metrics-bucket.html)
+     * to be enabled on the bucket. Set {@link BucketAlarmConfig.requestMetricsFilterId}
+     * to the ID of the request metrics configuration to create these 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#S3
+     */
+    recommendedAlarms?: BucketAlarmConfig | false;
 }
 /**
  * The build output of a {@link IBucketBuilder}. Contains the CDK constructs
@@ -48,6 +66,19 @@ export interface BucketBuilderResult {
      * logging was disabled or the user provided their own destination.
      */
     accessLogsBucket?: Bucket;
+    /**
+     * CloudWatch alarms created for the bucket, keyed by alarm name.
+     *
+     * Includes both AWS-recommended alarms and any custom alarms added
+     * via {@link IBucketBuilder.addAlarm}. Access individual alarms
+     * by key (e.g., `result.alarms.serverErrors`).
+     *
+     * 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#S3
+     */
+    alarms: Record<string, Alarm>;
 }
 /**
  * A fluent builder for configuring and creating an Amazon S3 bucket.
@@ -71,6 +102,8 @@ export interface BucketBuilderResult {
 export type IBucketBuilder = IBuilder<BucketBuilderProps, BucketBuilder>;
 declare class BucketBuilder implements Lifecycle<BucketBuilderResult> {
     props: Partial<BucketBuilderProps>;
+    private readonly customAlarms;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<Bucket>) => AlarmDefinitionBuilder<Bucket>): this;
     build(scope: IConstruct, id: string): BucketBuilderResult;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"bucket-builder.d.ts","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IAExC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA4C1D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}
+{"version":3,"file":"bucket-builder.d.ts","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAEzE,cAAM,aAAc,YAAW,SAAS,CAAC,mBAAmB,CAAC;IAC3D,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAM;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwC;IAErE,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB;CA8D1D;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAEpD"}

package/dist/bucket-builder.js

@@ -1,11 +1,18 @@
 import { RemovalPolicy } from "aws-cdk-lib";
 import { Bucket } from "aws-cdk-lib/aws-s3";
 import { Builder } from "@composurecdk/core";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import { createBucketAlarms } from "./bucket-alarms.js";
 import { BUCKET_DEFAULTS } from "./defaults.js";
 class BucketBuilder {
     props = {};
+    customAlarms = [];
+    addAlarm(key, configure) {
+        this.customAlarms.push(configure(new AlarmDefinitionBuilder(key)));
+        return this;
+    }
     build(scope, id) {
-        const { accessLogging, accessLogsPrefix, ...bucketProps } = this.props;
+        const { accessLogging, accessLogsPrefix, recommendedAlarms: alarmConfig, ...bucketProps } = this.props;
         const { accessLogging: defaultAccessLogging, accessLogsPrefix: defaultLogsPrefix, ...cdkDefaults } = BUCKET_DEFAULTS;
         const autoAccessLog = (accessLogging ?? defaultAccessLogging) && !bucketProps.serverAccessLogsBucket;
         if (accessLogsPrefix !== undefined && !autoAccessLog) {
@@ -18,6 +25,7 @@ class BucketBuilder {
         if (autoAccessLog) {
             accessLogsBucket = createBucketBuilder()
                 .accessLogging(false)
+                .versioned(false)
                 .removalPolicy(RemovalPolicy.RETAIN)
                 .build(scope, `${id}AccessLogs`).bucket;
             accessLogProps = {
@@ -31,9 +39,12 @@ class BucketBuilder {
             ...bucketProps,
             ...autoDeleteProps(bucketProps, BUCKET_DEFAULTS),
         };
+        const bucket = new Bucket(scope, id, mergedProps);
+        const alarms = createBucketAlarms(scope, id, bucket, alarmConfig, bucketProps.metrics ?? [], this.customAlarms);
         return {
-            bucket: new Bucket(scope, id, mergedProps),
+            bucket,
             accessLogsBucket,
+            alarms,
         };
     }
 }

package/dist/bucket-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAoB,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAiC,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AA2EhD,MAAM,aAAa;IACjB,KAAK,GAAgC,EAAE,CAAC;IAExC,KAAK,CAAC,KAAiB,EAAE,EAAU;QACjC,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACvE,MAAM,EACJ,aAAa,EAAE,oBAAoB,EACnC,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,WAAW,EACf,GAAG,eAAe,CAAC;QACpB,MAAM,aAAa,GACjB,CAAC,aAAa,IAAI,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC;QAEjF,IAAI,gBAAgB,KAAK,SAAS,IAAI,CAAC,aAAa,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,mEAAmE;gBACjE,qEAAqE;gBACrE,8CAA8C,CACjD,CAAC;QACJ,CAAC;QAED,IAAI,gBAAoC,CAAC;QACzC,IAAI,cAAc,GAAG,EAAE,CAAC;QAExB,IAAI,aAAa,EAAE,CAAC;YAClB,gBAAgB,GAAG,mBAAmB,EAAE;iBACrC,aAAa,CAAC,KAAK,CAAC;iBACpB,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC;iBACnC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC;YAC1C,cAAc,GAAG;gBACf,sBAAsB,EAAE,gBAAgB;gBACxC,sBAAsB,EAAE,gBAAgB,IAAI,iBAAiB;aAC9D,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,WAAW;YACd,GAAG,cAAc;YACjB,GAAG,WAAW;YACd,GAAG,eAAe,CAAC,WAAW,EAAE,eAAe,CAAC;SAClC,CAAC;QAEjB,OAAO;YACL,MAAM,EAAE,IAAI,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YAC1C,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CACtB,SAA+B,EAC/B,QAAqC;IAErC,MAAM,eAAe,GAAG,SAAS,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC;IAC1E,IAAI,eAAe,KAAK,aAAa,CAAC,OAAO,IAAI,SAAS,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3F,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAoC,aAAa,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"bucket-builder.js","sourceRoot":"","sources":["../src/bucket-builder.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { createBucketBuilder, type BucketBuilderResult, type IBucketBuilder, } from "./bucket-builder.js";
 export { BUCKET_DEFAULTS } from "./defaults.js";
+export { type BucketAlarmConfig } from "./alarm-config.js";
+export { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
 export { createBucketDeploymentBuilder, type BucketDeploymentBuilderResult, type IBucketDeploymentBuilder, } from "./bucket-deployment-builder.js";
 export { BUCKET_DEPLOYMENT_DEFAULTS } from "./bucket-deployment-defaults.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,6BAA6B,EAC7B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EACL,6BAA6B,EAC7B,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,GAC9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createBucketBuilder, } from "./bucket-builder.js";
 export { BUCKET_DEFAULTS } from "./defaults.js";
+export { BUCKET_ALARM_DEFAULTS } from "./alarm-defaults.js";
 export { createBucketDeploymentBuilder, } from "./bucket-deployment-builder.js";
 export { BUCKET_DEPLOYMENT_DEFAULTS } from "./bucket-deployment-defaults.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,6BAA6B,GAG9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EACL,6BAA6B,GAG9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/s3",
-  "version": "0.1.3",
+  "version": "0.3.2",
   "description": "Composable S3 bucket builder with well-architected defaults",
   "repository": {
     "type": "git",
@@ -35,16 +35,17 @@
   },
   "type": "module",
   "peerDependencies": {
-    "@composurecdk/core": "^0.1.0",
-    "@composurecdk/logs": "^0.1.0",
+    "@composurecdk/cloudwatch": "^0.3.0",
+    "@composurecdk/core": "^0.3.0",
+    "@composurecdk/logs": "^0.3.0",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "aws-cdk-lib": "^2.245.0",
+    "@types/node": "^25.6.0",
+    "aws-cdk-lib": "^2.250.0",
     "constructs": "^10.6.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
   }
 }