canopycms-cdk 0.0.67 → 0.0.68-int.94

package/README.md

@@ -14,6 +14,7 @@ AWS CDK constructs and EC2 worker for deploying CanopyCMS.
 - Lambda Function URL (for CloudFront origin)
 - EC2 Worker (t4g.nano spot in ASG, public subnet, EFS mount)
 - Security groups and IAM roles (least-privilege)
+- `attachTo(distribution)`: adds the editor's `/edit`, `/edit/*` and `/api/canopycms/*` behaviors (and, optionally, the CMS build's `assetPrefix` and the preview route) to a CloudFront distribution you already own
 
 **`CanopyCmsDistribution`** — CloudFront + DNS (optional):
 
@@ -21,8 +22,9 @@ AWS CDK constructs and EC2 worker for deploying CanopyCMS.
 - CloudFront distribution with Lambda Function URL origin
 - Route53 A/AAAA alias records
 - Cache policies: no-cache for API/editor, long-cache for static assets
+- Response headers: framing protection (`frame-ancestors 'self'`), `nosniff`, HSTS, `X-Robots-Tag: noindex`
 
-Use `CanopyCmsDistribution` if you don't have existing CloudFront infrastructure. Otherwise, use the `functionUrl` output from `CanopyCmsService` and wire it into your own CloudFront setup.
+Use `CanopyCmsDistribution` when the CMS gets its own domain. To serve the editor from an existing distribution, call `cmsService.attachTo(distribution)` instead of wiring the `functionUrl` by hand; see [Serving the editor from a distribution you already own](../../docs/deploying-to-aws.md#serving-the-editor-from-a-distribution-you-already-own).
 
 ### EC2 Worker
 

package/dist/constructs/cms-distribution.d.ts

@@ -98,17 +98,18 @@ export interface CanopyCmsDistributionProps {
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
  *
- * Use this if you don't have existing CloudFront infrastructure.
- * If you do, use the functionUrl output from CanopyCmsService
- * and wire it into your own CloudFront setup.
+ * Use this when the CMS gets a domain of its own. To serve the editor from a
+ * distribution you already own, use `CanopyCmsService.attachTo` instead.
  *
  * Creates:
  * - ACM certificate (DNS validated) — unless provided
  * - CloudFront distribution with Function URL origin
  * - Route53 A/AAAA alias records
- * - Cache policies: no-cache for /api/* and /edit*, cache /_next/static/*
+ * - Cache policies: no-cache default behavior, cache /_next/static/*
  * - Viewer-request CloudFront Function setting x-forwarded-host (redirect-URL
  *   derivation behind the Host-stripping OAC origin)
+ * - The editor's response headers policy (framing protection, `noindex`) on
+ *   both of its own behaviors
  * - `AssetSupport`'s `/assets/*` and `/assets/t/*` behaviors, in the required
  *   order, when the `assetSupport` prop is passed
  */

package/dist/constructs/cms-distribution.js

@@ -1,6 +1,7 @@
 import { Construct } from 'constructs';
-import { Duration, Stack, Token, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_certificatemanager as acm, aws_route53 as route53, aws_route53_targets as targets, } from 'aws-cdk-lib';
-import { DEFAULT_CMS_LAMBDA_TIMEOUT, MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT } from './cms-service.js';
+import { Stack, Token, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_certificatemanager as acm, aws_route53 as route53, aws_route53_targets as targets, } from 'aws-cdk-lib';
+import { DEFAULT_CMS_LAMBDA_TIMEOUT } from './cms-service.js';
+import { assertOriginReadTimeout, createEditorResponseHeadersPolicy, createForwardedHostFunction, createStaticCachePolicy, lambdaBehaviorOptions, } from './editor-routing.js';
 import { ASSETS_PATH_PATTERN, ASSETS_TRANSFORM_PATH_PATTERN, ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS, } from './asset-support.js';
 /**
  * Merge caller behaviors over this construct's own, preserving THE CALLER'S
@@ -128,17 +129,18 @@ function assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport) {
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
  *
- * Use this if you don't have existing CloudFront infrastructure.
- * If you do, use the functionUrl output from CanopyCmsService
- * and wire it into your own CloudFront setup.
+ * Use this when the CMS gets a domain of its own. To serve the editor from a
+ * distribution you already own, use `CanopyCmsService.attachTo` instead.
  *
  * Creates:
  * - ACM certificate (DNS validated) — unless provided
  * - CloudFront distribution with Function URL origin
  * - Route53 A/AAAA alias records
- * - Cache policies: no-cache for /api/* and /edit*, cache /_next/static/*
+ * - Cache policies: no-cache default behavior, cache /_next/static/*
  * - Viewer-request CloudFront Function setting x-forwarded-host (redirect-URL
  *   derivation behind the Host-stripping OAC origin)
+ * - The editor's response headers policy (framing protection, `noindex`) on
+ *   both of its own behaviors
  * - `AssetSupport`'s `/assets/*` and `/assets/t/*` behaviors, in the required
  *   order, when the `assetSupport` prop is passed
  */
@@ -193,75 +195,26 @@ export class CanopyCmsDistribution extends Construct {
         // entirely when unset, so CloudFront's 30s service default applies and
         // silently halves the CMS Lambda's 60s budget. See the prop's doc comment.
         const readTimeout = props.originReadTimeout ?? DEFAULT_CMS_LAMBDA_TIMEOUT;
-        if (readTimeout.toSeconds() > MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()) {
-            throw new Error(`CanopyCmsDistribution: originReadTimeout is ${readTimeout.toSeconds()}s, but CloudFront ` +
-                `allows at most ${MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT.toSeconds()}s without a service-quota ` +
-                `increase. Either lower the CMS Lambda's timeout to match, or request a quota increase for ` +
-                `"Origin response timeout" and pass the higher value explicitly. Deploying with a shorter ` +
-                `origin timeout than the Lambda's would 504 at the edge on requests that actually succeed.`);
-        }
+        assertOriginReadTimeout(readTimeout, 'CanopyCmsDistribution');
         const origin = origins.FunctionUrlOrigin.withOriginAccessControl(props.functionUrl, {
             readTimeout,
         });
-        // API/editor routes take AWS's managed CACHING_DISABLED policy as it is:
-        // CloudFront rejects ANY non-none cache-key setting on a caching-disabled
-        // policy - `Authorization` in a header allowlist, and equally
-        // cookieBehavior/queryStringBehavior `all()` ("The parameter CookieBehavior
-        // is invalid for policy with caching disabled"). With TTL 0 the cache key is
-        // meaningless anyway, and the origin still receives the full viewer request
-        // (headers/cookies/query string, minus Host - forwarding Host would break
-        // the OAC-signed Function URL) via the ALL_VIEWER_EXCEPT_HOST_HEADER origin
-        // request policy on the behavior.
-        const noCachePolicy = cloudfront.CachePolicy.CACHING_DISABLED;
-        const staticCachePolicy = new cloudfront.CachePolicy(this, 'StaticCachePolicy', {
-            defaultTtl: Duration.days(365),
-            maxTtl: Duration.days(365),
-            minTtl: Duration.days(365),
-            headerBehavior: cloudfront.CacheHeaderBehavior.none(),
-            queryStringBehavior: cloudfront.CacheQueryStringBehavior.none(),
-            cookieBehavior: cloudfront.CacheCookieBehavior.none(),
-        });
-        // CloudFront gives the origin the Function URL's own Host (forwarding the
-        // viewer Host would break the OAC SigV4 signature), and Lambda Web Adapter
-        // forwards no `x-forwarded-*` headers of its own - so without this function,
-        // Clerk/Next derive sign-in redirect URLs from the IAM-authed Function URL
-        // host instead of the public domain, and the redirect 403s (direct Function
-        // URL hits are rejected).
-        //
-        // ONLY x-forwarded-host: x-forwarded-proto is on CloudFront Functions'
-        // DISALLOWED header list and setting it fails every request with 502
-        // FunctionValidationError. Proto is unambiguous anyway - viewer-facing
-        // CloudFront is HTTPS-only via REDIRECT_TO_HTTPS.
-        const forwardedHostFunction = new cloudfront.Function(this, 'ForwardedHostFunction', {
-            code: cloudfront.FunctionCode.fromInline([
-                'function handler(event) {',
-                '  var request = event.request;',
-                "  request.headers['x-forwarded-host'] = { value: request.headers.host.value };",
-                '  return request;',
-                '}',
-            ].join('\n')),
-        });
+        const staticCachePolicy = createStaticCachePolicy(this, 'StaticCachePolicy');
+        const forwardedHostFunction = createForwardedHostFunction(this, 'ForwardedHostFunction');
+        const responseHeadersPolicy = createEditorResponseHeadersPolicy(this, 'EditorResponseHeadersPolicy');
         this.distribution = new cloudfront.Distribution(this, 'Distribution', {
             domainNames: [props.domainName],
             certificate,
             defaultBehavior: {
                 origin,
-                cachePolicy: noCachePolicy,
-                viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
-                allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
-                originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
-                functionAssociations: [
-                    {
-                        function: forwardedHostFunction,
-                        eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
-                    },
-                ],
+                ...lambdaBehaviorOptions(forwardedHostFunction, responseHeadersPolicy),
             },
             additionalBehaviors: mergeBehaviors({
                 '/_next/static/*': {
                     origin,
                     cachePolicy: staticCachePolicy,
                     viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+                    responseHeadersPolicy,
                 },
             }, props.additionalBehaviors, props.assetSupport !== undefined),
         });

package/dist/constructs/cms-service.d.ts

@@ -1,6 +1,7 @@
 import { Construct } from 'constructs';
-import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
+import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
 import type { IBucket } from 'aws-cdk-lib/aws-s3';
+import type { CanopyCmsAttachOptions } from './editor-routing.js';
 /**
  * Default CMS Lambda timeout.
  *
@@ -20,8 +21,6 @@ import type { IBucket } from 'aws-cdk-lib/aws-s3';
  * than deploying a configuration that would 504.
  */
 export declare const DEFAULT_CMS_LAMBDA_TIMEOUT: Duration;
-/** CloudFront's maximum origin read timeout without a service-quota increase. */
-export declare const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT: Duration;
 export interface CanopyCmsServiceProps {
     /** Docker image for the CMS Lambda function */
     cmsDockerImage: lambda.DockerImageCode;
@@ -360,4 +359,25 @@ export declare class CanopyCmsService extends Construct {
     /** The EC2 worker's CloudWatch log group (worker stdout/stderr) */
     readonly workerLogGroup: logs.LogGroup;
     constructor(scope: Construct, id: string, props: CanopyCmsServiceProps);
+    /**
+     * Serve the editor from a CloudFront distribution you already own, such as
+     * the site's: adds `/edit`, `/edit/*` and `/api/canopycms/*` behaviors
+     * (plus any `previewPrefix` and `editorAssetPrefix` routes) to this
+     * service's Function URL, behind OAC, with
+     * an origin read timeout equal to {@link timeout}, no caching, the whole
+     * viewer request forwarded, an `x-forwarded-host` viewer-request function and
+     * the editor's response headers policy (framing protection, `noindex`).
+     *
+     * The behaviors are appended. Synth fails if a behavior listed before them
+     * matches an editor route, since CloudFront would never reach the editor's.
+     * It warns when the distribution has custom error responses, which also
+     * rewrite the API's errors.
+     *
+     * Pass `editorAssetPrefix` with the CMS build's Next `assetPrefix`, so the
+     * editor's chunks stay out of the site's `/_next/static/*`, and
+     * `previewPrefix` with a static-export site's preview route.
+     * `AssetSupport.attachTo` adds `/assets/*`. Use `CanopyCmsDistribution`
+     * instead when the CMS gets a domain of its own.
+     */
+    attachTo(distribution: cloudfront.Distribution, options?: CanopyCmsAttachOptions): void;
 }

package/dist/constructs/cms-service.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { Construct } from 'constructs';
 import { Duration, RemovalPolicy, Stack, Token, aws_ec2 as ec2, aws_efs as efs, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_s3_assets as s3assets, aws_logs as logs, } from 'aws-cdk-lib';
 import { attachLambdaExecutionPolicies } from './lambda-execution-role.js';
+import { attachEditorBehaviors } from './editor-routing.js';
 // This package (`canopycms-cdk`) is `"type": "module"`, so its compiled output
 // is real ESM and `__dirname` is not a global there - the worker asset path
 // below throws `__dirname is not defined` under a real ESM runtime (e.g. `tsx`)
@@ -455,8 +456,6 @@ function assertGitHubAuthProps(props) {
  * than deploying a configuration that would 504.
  */
 export const DEFAULT_CMS_LAMBDA_TIMEOUT = Duration.seconds(60);
-/** CloudFront's maximum origin read timeout without a service-quota increase. */
-export const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT = Duration.seconds(60);
 /**
  * Core CDK construct for CanopyCMS deployment.
  *
@@ -986,4 +985,27 @@ export class CanopyCmsService extends Construct {
         // EC2-health-checked ASG never notices.
         this.workerAsg.node.addDependency(this.fileSystem.mountTargetsAvailable);
     }
+    /**
+     * Serve the editor from a CloudFront distribution you already own, such as
+     * the site's: adds `/edit`, `/edit/*` and `/api/canopycms/*` behaviors
+     * (plus any `previewPrefix` and `editorAssetPrefix` routes) to this
+     * service's Function URL, behind OAC, with
+     * an origin read timeout equal to {@link timeout}, no caching, the whole
+     * viewer request forwarded, an `x-forwarded-host` viewer-request function and
+     * the editor's response headers policy (framing protection, `noindex`).
+     *
+     * The behaviors are appended. Synth fails if a behavior listed before them
+     * matches an editor route, since CloudFront would never reach the editor's.
+     * It warns when the distribution has custom error responses, which also
+     * rewrite the API's errors.
+     *
+     * Pass `editorAssetPrefix` with the CMS build's Next `assetPrefix`, so the
+     * editor's chunks stay out of the site's `/_next/static/*`, and
+     * `previewPrefix` with a static-export site's preview route.
+     * `AssetSupport.attachTo` adds `/assets/*`. Use `CanopyCmsDistribution`
+     * instead when the CMS gets a domain of its own.
+     */
+    attachTo(distribution, options) {
+        attachEditorBehaviors(distribution, this.functionUrl, this.timeout, options);
+    }
 }

package/dist/constructs/editor-routing.d.ts

@@ -0,0 +1,131 @@
+import { Construct } from 'constructs';
+import { Duration, aws_cloudfront as cloudfront, aws_lambda as lambda } from 'aws-cdk-lib';
+/** CloudFront's maximum origin read timeout without a service-quota increase. */
+export declare const MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT: Duration;
+/**
+ * The routes the editor needs from the CMS Lambda on a distribution it shares
+ * with a site: the editor page and the catch-all API route `canopycms init`
+ * scaffolds. `/edit` and `/edit/*` rather than `/edit*`, which also matches
+ * `/editorial` and `/edit-assets/…` and so takes site pages away from the site.
+ *
+ * Not included, because on a shared distribution they belong to the site:
+ * `/_next/static/*` (the CMS build moves its chunks out of it with Next's
+ * `assetPrefix`; see `editorAssetPrefix`) and `/assets/*`
+ * (`AssetSupport.attachTo` owns it).
+ */
+export declare const EDITOR_PATH_PATTERNS: readonly ["/edit", "/edit/*", "/api/canopycms/*"];
+/**
+ * Whether a CloudFront path pattern matches a request path: `*` is any run of
+ * characters, `?` exactly one, matching is case-sensitive, and the pattern's
+ * leading `/` is optional.
+ */
+export declare function cloudFrontPathPatternMatches(pattern: string, path: string): boolean;
+/**
+ * Throws when the origin read timeout exceeds the 60s CloudFront accepts
+ * without a quota increase, which it would reject at deploy. Neither construct
+ * takes a higher, quota-raised value.
+ */
+export declare function assertOriginReadTimeout(readTimeout: Duration, owner: string): void;
+/**
+ * The viewer-request function every Lambda behavior needs. CloudFront gives
+ * the origin the Function URL's own Host (forwarding the viewer Host would
+ * break the OAC SigV4 signature), and Lambda Web Adapter adds no
+ * `x-forwarded-*` headers, so without this Clerk/Next derive sign-in redirect
+ * URLs from the IAM-authed Function URL host and the redirect 403s.
+ *
+ * Only `x-forwarded-host`: `x-forwarded-proto` is on CloudFront Functions'
+ * disallowed list and setting it fails every request with a 502. The viewer
+ * side is HTTPS-only, so proto is unambiguous anyway.
+ */
+export declare function createForwardedHostFunction(scope: Construct, id: string): cloudfront.Function;
+/**
+ * Response headers for everything the CMS Lambda serves.
+ *
+ * - `frame-ancestors 'self'` (plus `X-Frame-Options: SAMEORIGIN` for browsers
+ *   that ignore it) stops other sites framing the editor. `'self'` keeps the
+ *   editor's own preview iframe working, which frames same-origin site pages.
+ * - Both framing headers have `override: false`, so an origin that sends its
+ *   own CSP keeps it whole; when that CSP has no `frame-ancestors` and the
+ *   origin sends no `X-Frame-Options`, this one applies.
+ * - `X-Robots-Tag: noindex` overrides: nothing the Lambda serves is meant to
+ *   be indexed.
+ * - No `Cross-Origin-Opener-Policy`: it can cut the `window.opener` link a
+ *   popup-based OAuth sign-in reports back through.
+ */
+export declare function createEditorResponseHeadersPolicy(scope: Construct, id: string): cloudfront.ResponseHeadersPolicy;
+/**
+ * A year-long cache for content-hashed build output. The cache key carries no
+ * header, cookie or query string, so every viewer shares one copy.
+ */
+export declare function createStaticCachePolicy(scope: Construct, id: string): cloudfront.CachePolicy;
+/**
+ * Behavior options for a route the CMS Lambda serves. The managed
+ * CACHING_DISABLED policy as it is: CloudFront rejects any non-none cache-key
+ * setting on a caching-disabled policy, and the origin still gets the whole
+ * viewer request (headers, cookies, query string, minus Host, which would
+ * break the OAC signature) through ALL_VIEWER_EXCEPT_HOST_HEADER.
+ */
+export declare function lambdaBehaviorOptions(viewerRequestFunction: cloudfront.FunctionAssociation['function'] | undefined, responseHeadersPolicy: NonNullable<cloudfront.AddBehaviorOptions['responseHeadersPolicy']>): cloudfront.AddBehaviorOptions;
+/** Options for `CanopyCmsService.attachTo`. */
+export interface CanopyCmsAttachOptions {
+    /**
+     * Viewer-request function for the editor behaviors, in place of the
+     * `x-forwarded-host` function `attachTo` otherwise creates. CloudFront allows
+     * one per behavior, so pass this when the distribution's own function must
+     * run on every route.
+     *
+     * It must set `x-forwarded-host` from the viewer's Host, or sign-in
+     * redirects point at the Function URL and 403. It must not gate on HTTP
+     * Basic auth: the API answers 401 without `WWW-Authenticate`, and a browser
+     * that sees that drops its cached Basic credential and prompts again.
+     *
+     * @default - a function that sets `x-forwarded-host` and nothing else
+     */
+    viewerRequestFunction?: cloudfront.IFunction;
+    /**
+     * Options merged into the editor and preview behaviors, after this construct's
+     * own; keys whose value is `undefined` are ignored. A `responseHeadersPolicy`
+     * here replaces the editor's framing protection, so it must carry its own.
+     * `functionAssociations` here replaces the viewer-request function as well,
+     * which is why it cannot be combined with `viewerRequestFunction`.
+     *
+     * @default - no overrides
+     */
+    behaviorOverrides?: Partial<cloudfront.AddBehaviorOptions>;
+    /**
+     * The CMS build's Next `assetPrefix`, such as `'/edit-assets'`: adds a
+     * `/<prefix>/*` behavior to the Lambda with a year-long cache, since the
+     * chunks under it are content-hashed.
+     *
+     * A CMS build that shares a distribution with a static site needs one.
+     * Without it the editor page loads its chunks from `/_next/static/*`, which
+     * the site serves, and they 404. Set `assetPrefix` in the CMS build's
+     * `next.config` only (not the static export's) and pass the same value here.
+     *
+     * A path starting with `/`, without a trailing `/` or wildcards, and
+     * overlapping neither the editor's routes, `/_next/*` nor AssetSupport's
+     * `/assets/*`. Of `behaviorOverrides`, only `responseHeadersPolicy` applies
+     * to this behavior.
+     *
+     * @default - no asset-prefix behavior
+     */
+    editorAssetPrefix?: string;
+    /**
+     * The path of the CMS-only preview route, the same value as
+     * `editor.previewPrefix` in the CanopyCMS config (e.g. `'/preview'`): adds
+     * `<prefix>` and `<prefix>/*` behaviors with the editor routes' options, so
+     * the editor's preview pane reaches the CMS rather than the site.
+     *
+     * Validated like `editorAssetPrefix`, and must not overlap it either. An
+     * absolute `https://` `previewPrefix` is another origin and needs nothing
+     * here.
+     *
+     * @default - no preview behaviors
+     */
+    previewPrefix?: string;
+}
+/**
+ * Attach the editor's behaviors to a distribution. See
+ * `CanopyCmsService.attachTo`, which is the public entry point.
+ */
+export declare function attachEditorBehaviors(distribution: cloudfront.Distribution, functionUrl: lambda.IFunctionUrl, readTimeout: Duration, options?: CanopyCmsAttachOptions): void;