@composurecdk/cloudfront 0.1.2

package/dist/defaults.d.ts

@@ -0,0 +1,12 @@
+import type { DistributionBuilderProps } from "./distribution-builder.js";
+/**
+ * Secure, AWS-recommended defaults applied to every CloudFront distribution
+ * built with {@link createDistributionBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * The `defaultBehavior` defaults (viewer protocol policy, response headers
+ * policy) are deep-merged with user-provided behavior options in `build()`,
+ * then the resolved origin is injected.
+ */
+export declare const DISTRIBUTION_DEFAULTS: Partial<DistributionBuilderProps>;
+//# 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":"AAOA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,wBAAwB,CAkDnE,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,56 @@
+import { HttpVersion, PriceClass, ResponseHeadersPolicy, SecurityPolicyProtocol, ViewerProtocolPolicy, } from "aws-cdk-lib/aws-cloudfront";
+/**
+ * Secure, AWS-recommended defaults applied to every CloudFront distribution
+ * built with {@link createDistributionBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * The `defaultBehavior` defaults (viewer protocol policy, response headers
+ * policy) are deep-merged with user-provided behavior options in `build()`,
+ * then the resolved origin is injected.
+ */
+export const DISTRIBUTION_DEFAULTS = {
+    /**
+     * Automatically create an S3 logging bucket for CloudFront standard access logs.
+     * Access logging provides an audit trail of all viewer requests for security
+     * monitoring and troubleshooting.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     */
+    accessLogging: true,
+    /**
+     * Use the cheapest price class — edge locations in North America and Europe.
+     * Sufficient for most small websites and avoids costs from global edge locations.
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PriceClass.html
+     */
+    priceClass: PriceClass.PRICE_CLASS_100,
+    /**
+     * Enable HTTP/2 and HTTP/3 (QUIC) for improved performance. HTTP/3 is
+     * backwards-compatible — viewers that don't support it fall back to HTTP/2.
+     * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html#DownloadDistValuesSupportedHTTPVersions
+     */
+    httpVersion: HttpVersion.HTTP2_AND_3,
+    /**
+     * Serve index.html for the root path.
+     * Standard for static website hosting.
+     */
+    defaultRootObject: "index.html",
+    /**
+     * Require TLS 1.2 (2021 policy) as the minimum protocol version.
+     * Prevents negotiation of older, less secure TLS versions.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-in-transit.html
+     */
+    minimumProtocolVersion: SecurityPolicyProtocol.TLS_V1_2_2021,
+    defaultBehavior: {
+        /**
+         * Redirect HTTP to HTTPS — ensures all viewer traffic is encrypted in transit.
+         * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-in-transit.html
+         */
+        viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+        /**
+         * Apply the managed security headers policy (HSTS, X-Content-Type-Options,
+         * X-Frame-Options, etc.).
+         * @see https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-response-headers-policies.html
+         */
+        responseHeadersPolicy: ResponseHeadersPolicy.SECURITY_HEADERS,
+    },
+};
+//# 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,EACL,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsC;IACtE;;;;;OAKG;IACH,aAAa,EAAE,IAAI;IAEnB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC,eAAe;IAEtC;;;;OAIG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW;IAEpC;;;OAGG;IACH,iBAAiB,EAAE,YAAY;IAE/B;;;;OAIG;IACH,sBAAsB,EAAE,sBAAsB,CAAC,aAAa;IAE5D,eAAe,EAAE;QACf;;;WAGG;QACH,oBAAoB,EAAE,oBAAoB,CAAC,iBAAiB;QAE5D;;;;WAIG;QACH,qBAAqB,EAAE,qBAAqB,CAAC,gBAAgB;KAC9D;CACF,CAAC"}

package/dist/distribution-builder.d.ts

@@ -0,0 +1,128 @@
+import { Distribution, type DistributionProps, type IOrigin, type AddBehaviorOptions } from "aws-cdk-lib/aws-cloudfront";
+import { type Bucket } from "aws-cdk-lib/aws-s3";
+import { type IConstruct } from "constructs";
+import { type IBuilder, type Lifecycle, type Resolvable } from "@composurecdk/core";
+/**
+ * Configuration properties for the CloudFront distribution builder.
+ *
+ * Extends the CDK {@link DistributionProps} with additional builder-specific
+ * options. The `defaultBehavior` field is replaced with {@link AddBehaviorOptions}
+ * (which excludes `origin`) because the origin is set separately via the
+ * {@link IDistributionBuilder.origin | origin()} method, which supports
+ * {@link Resolvable} for cross-component wiring.
+ *
+ * The `enableLogging` CDK prop is replaced by {@link accessLogging}, which
+ * auto-creates a logging bucket with secure defaults when enabled.
+ */
+export interface DistributionBuilderProps extends Omit<DistributionProps, "defaultBehavior" | "enableLogging"> {
+    /**
+     * Whether to automatically create an S3 bucket for CloudFront standard
+     * access logging.
+     *
+     * When `true`, the builder creates a logging bucket using
+     * {@link createBucketBuilder} (with its secure defaults) and configures it
+     * as the distribution's log destination. The created bucket is returned in
+     * the build result as `accessLogsBucket`.
+     *
+     * When `false`, no logging bucket is created. You can still provide your
+     * own bucket via `logBucket`.
+     *
+     * This setting is ignored when `logBucket` is provided — the user-supplied
+     * bucket takes precedence.
+     */
+    accessLogging?: boolean;
+    /**
+     * Options for the default cache behavior, excluding `origin`.
+     *
+     * The origin is set via the {@link IDistributionBuilder.origin | origin()}
+     * method and injected at build time. All other behavior options (cache
+     * policy, function associations, viewer protocol policy, etc.) can be
+     * configured here.
+     */
+    defaultBehavior?: AddBehaviorOptions;
+}
+/**
+ * The build output of a {@link IDistributionBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface DistributionBuilderResult {
+    /** The CloudFront distribution construct created by the builder. */
+    distribution: Distribution;
+    /**
+     * The S3 bucket created for access logging, or `undefined` if access
+     * logging was disabled or the user provided their own bucket.
+     */
+    accessLogsBucket?: Bucket;
+}
+/**
+ * A fluent builder for configuring and creating a CloudFront distribution.
+ *
+ * Configuration properties from CDK {@link DistributionProps} are exposed as
+ * overloaded getter/setter methods via the builder proxy. The origin is set
+ * via the {@link origin} method, which accepts a concrete {@link IOrigin} or
+ * a {@link Ref} for cross-component wiring.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates
+ * a CloudFront distribution with the configured properties and returns a
+ * {@link DistributionBuilderResult}.
+ *
+ * @example
+ * ```ts
+ * const cdn = createDistributionBuilder()
+ *   .origin(ref("site", (r: BucketBuilderResult) =>
+ *     S3BucketOrigin.withOriginAccessControl(r.bucket)))
+ *   .errorResponses([{
+ *     httpStatus: 404,
+ *     responsePagePath: "/index.html",
+ *     responseHttpStatus: 200,
+ *   }]);
+ * ```
+ */
+export type IDistributionBuilder = IBuilder<DistributionBuilderProps, DistributionBuilder>;
+declare class DistributionBuilder implements Lifecycle<DistributionBuilderResult> {
+    props: Partial<DistributionBuilderProps>;
+    private _origin?;
+    /**
+     * Sets the default origin for the distribution.
+     *
+     * Accepts a concrete {@link IOrigin} or a {@link Ref} that resolves to one
+     * at build time — enabling cross-component wiring with S3 buckets.
+     *
+     * @param origin - The origin or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    origin(origin: Resolvable<IOrigin>): this;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): DistributionBuilderResult;
+}
+/**
+ * Creates a new {@link IDistributionBuilder} for configuring a CloudFront distribution.
+ *
+ * This is the entry point for defining a CloudFront distribution component.
+ * The returned builder exposes every {@link DistributionBuilderProps} property
+ * as a fluent setter/getter, plus {@link IDistributionBuilder.origin | origin()}
+ * for setting the default origin with Ref support. It implements {@link Lifecycle}
+ * for use with {@link compose}.
+ *
+ * @returns A fluent builder for a CloudFront distribution.
+ *
+ * @example
+ * ```ts
+ * const cdn = createDistributionBuilder()
+ *   .origin(ref("site", (r: BucketBuilderResult) =>
+ *     S3BucketOrigin.withOriginAccessControl(r.bucket)))
+ *   .comment("Community website CDN");
+ *
+ * // Use standalone:
+ * const result = cdn.build(stack, "CDN");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site: createBucketBuilder(), cdn },
+ *   { site: [], cdn: ["site"] },
+ * );
+ * ```
+ */
+export declare function createDistributionBuilder(): IDistributionBuilder;
+export {};
+//# sourceMappingURL=distribution-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"distribution-builder.d.ts","sourceRoot":"","sources":["../src/distribution-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAI5B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,iBAAiB,EACjB,iBAAiB,GAAG,eAAe,CACpC;IACC;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,YAAY,EAAE,YAAY,CAAC;IAE3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,wBAAwB,EAAE,mBAAmB,CAAC,CAAC;AAE3F,cAAM,mBAAoB,YAAW,SAAS,CAAC,yBAAyB,CAAC;IACvE,KAAK,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAM;IAC9C,OAAO,CAAC,OAAO,CAAC,CAAsB;IAEtC;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI;IAKzC,KAAK,CACH,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,yBAAyB;CAgD7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,yBAAyB,IAAI,oBAAoB,CAEhE"}

package/dist/distribution-builder.js

@@ -0,0 +1,90 @@
+import { Distribution, } from "aws-cdk-lib/aws-cloudfront";
+import { RemovalPolicy } from "aws-cdk-lib";
+import { Builder, resolve, } from "@composurecdk/core";
+import { createBucketBuilder } from "@composurecdk/s3";
+import { DISTRIBUTION_DEFAULTS } from "./defaults.js";
+class DistributionBuilder {
+    props = {};
+    _origin;
+    /**
+     * Sets the default origin for the distribution.
+     *
+     * Accepts a concrete {@link IOrigin} or a {@link Ref} that resolves to one
+     * at build time — enabling cross-component wiring with S3 buckets.
+     *
+     * @param origin - The origin or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    origin(origin) {
+        this._origin = origin;
+        return this;
+    }
+    build(scope, id, context) {
+        const resolvedOrigin = this._origin ? resolve(this._origin, context ?? {}) : undefined;
+        if (!resolvedOrigin) {
+            throw new Error(`DistributionBuilder "${id}" requires an origin. ` +
+                `Call .origin() with an IOrigin or a Ref to one.`);
+        }
+        const { accessLogging, defaultBehavior: userBehavior, ...distProps } = this.props;
+        const { accessLogging: defaultAccessLogging, defaultBehavior: defaultBehavior, ...cdkDefaults } = DISTRIBUTION_DEFAULTS;
+        const autoAccessLog = (accessLogging ?? defaultAccessLogging) && !distProps.logBucket;
+        let accessLogsBucket;
+        let accessLogProps = {};
+        if (autoAccessLog) {
+            accessLogsBucket = createBucketBuilder()
+                .accessLogging(false)
+                .removalPolicy(RemovalPolicy.RETAIN)
+                .build(scope, `${id}AccessLogs`).bucket;
+            accessLogProps = {
+                enableLogging: true,
+                logBucket: accessLogsBucket,
+            };
+        }
+        const mergedProps = {
+            ...cdkDefaults,
+            ...accessLogProps,
+            ...distProps,
+            defaultBehavior: {
+                ...defaultBehavior,
+                ...userBehavior,
+                origin: resolvedOrigin,
+            },
+        };
+        return {
+            distribution: new Distribution(scope, id, mergedProps),
+            accessLogsBucket,
+        };
+    }
+}
+/**
+ * Creates a new {@link IDistributionBuilder} for configuring a CloudFront distribution.
+ *
+ * This is the entry point for defining a CloudFront distribution component.
+ * The returned builder exposes every {@link DistributionBuilderProps} property
+ * as a fluent setter/getter, plus {@link IDistributionBuilder.origin | origin()}
+ * for setting the default origin with Ref support. It implements {@link Lifecycle}
+ * for use with {@link compose}.
+ *
+ * @returns A fluent builder for a CloudFront distribution.
+ *
+ * @example
+ * ```ts
+ * const cdn = createDistributionBuilder()
+ *   .origin(ref("site", (r: BucketBuilderResult) =>
+ *     S3BucketOrigin.withOriginAccessControl(r.bucket)))
+ *   .comment("Community website CDN");
+ *
+ * // Use standalone:
+ * const result = cdn.build(stack, "CDN");
+ *
+ * // Or compose into a system:
+ * const system = compose(
+ *   { site: createBucketBuilder(), cdn },
+ *   { site: [], cdn: ["site"] },
+ * );
+ * ```
+ */
+export function createDistributionBuilder() {
+    return Builder(DistributionBuilder);
+}
+//# sourceMappingURL=distribution-builder.js.map

package/dist/distribution-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution-builder.js","sourceRoot":"","sources":["../src/distribution-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAIb,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EACL,OAAO,EAGP,OAAO,GAER,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAwFtD,MAAM,mBAAmB;IACvB,KAAK,GAAsC,EAAE,CAAC;IACtC,OAAO,CAAuB;IAEtC;;;;;;;;OAQG;IACH,MAAM,CAAC,MAA2B;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CACH,KAAiB,EACjB,EAAU,EACV,OAAgC;QAEhC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEvF,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,wBAAwB,EAAE,wBAAwB;gBAChD,iDAAiD,CACpD,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QAClF,MAAM,EACJ,aAAa,EAAE,oBAAoB,EACnC,eAAe,EAAE,eAAe,EAChC,GAAG,WAAW,EACf,GAAG,qBAAqB,CAAC;QAC1B,MAAM,aAAa,GAAG,CAAC,aAAa,IAAI,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;QAEtF,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,aAAa,EAAE,IAAI;gBACnB,SAAS,EAAE,gBAAgB;aAC5B,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG;YAClB,GAAG,WAAW;YACd,GAAG,cAAc;YACjB,GAAG,SAAS;YACZ,eAAe,EAAE;gBACf,GAAG,eAAe;gBAClB,GAAG,YAAY;gBACf,MAAM,EAAE,cAAc;aACvB;SACmB,CAAC;QAEvB,OAAO;YACL,YAAY,EAAE,IAAI,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC;YACtD,gBAAgB;SACjB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,OAAO,CAAgD,mBAAmB,CAAC,CAAC;AACrF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createDistributionBuilder, type DistributionBuilderResult, type IDistributionBuilder, } from "./distribution-builder.js";
+export { DISTRIBUTION_DEFAULTS } from "./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,yBAAyB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createDistributionBuilder, } from "./distribution-builder.js";
+export { DISTRIBUTION_DEFAULTS } from "./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,yBAAyB,GAG1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@composurecdk/cloudfront",
+  "version": "0.1.2",
+  "description": "Composable CloudFront distribution builder with well-architected defaults",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/laazyj/composureCDK",
+    "directory": "packages/cloudfront"
+  },
+  "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 --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "keywords": [],
+  "author": "Jason Duffett (https://github.com/laazyj)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@composurecdk/core": "^0.1.0",
+    "@composurecdk/s3": "^0.1.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "aws-cdk-lib": "^2.245.0",
+    "constructs": "^10.6.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}