canopycms-cdk 0.0.67 → 0.0.68-int.100

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/asset-support.d.ts

@@ -128,50 +128,68 @@ export interface AssetSupportProps {
      */
     readonly autoDeleteObjects?: boolean;
     /**
-     * Require the transform Lambda's code asset to carry proof that it was
-     * built with its native sharp binary (the `.deployable` marker written by
-     * `build:lambda`). Leave this ON for anything that can reach a real
-     * deploy.
+     * A replica of the bucket's `assets/` prefix. Both public behaviors fail over
+     * to it on 500, 502, 503 or 504 from the primary, never on a miss: the
+     * replica only holds what the primary has. With `lazyPublicTransforms`,
+     * `/assets/t/*`'s one fallback slot is the transform Lambda, so only
+     * `/assets/*` gets the replica.
      *
-     * Set to `false` ONLY in this package's own tests, which synth against the
-     * cheap `--skip-native` fixture bundle `build:test-fixtures` produces: the
-     * suite never executes the handler, so the binary is irrelevant to what it
-     * asserts, and requiring a real build would put a live `npm install sharp` in
-     * front of every test run and price the suite out of CI.
+     * It is read through its own OAC, whose grant CDK writes only on a bucket it
+     * owns: an imported replica's policy must allow this distribution itself.
+     * Import one in another region with `Bucket.fromBucketAttributes({ bucketName,
+     * region })` so its regional domain name is right. Replication must cover
+     * `assets/`; `materialize-assets` writes only the primary.
      *
-     * Adopters never need this: the published package's asset is built by
-     * `prepack`'s full `build:lambda`, so the marker is always present.
+     * @default - no failover
+     */
+    readonly replicaBucket?: s3.IBucket;
+    /**
+     * Compute a missing `/assets/t/*` derivative on request with a transform
+     * Lambda, instead of serving only what `canopycms materialize-assets` wrote.
+     * Off, the public path computes nothing and an unmaterialized URL is a miss,
+     * which is also what a live preview on another origin than the editor shows
+     * for a draft's new crop.
      *
-     * @default true
+     * On, anyone can mint any allowlisted transform of a public asset - bounded
+     * per asset except crop, at ~10^16 rects - capped by reserved concurrency and
+     * an `assets/t/` expiry that applies only to objects the Lambda writes, which
+     * carry the tag `canopy-transform=lazy`: what `materialize-assets` writes is
+     * never expired. On a BYO `bucket` this construct cannot write that rule, so
+     * lazy mode there requires an explicit `transformOutputRetention`.
+     *
+     * @default false
      */
-    readonly requireDeployableBundle?: boolean;
+    readonly lazyPublicTransforms?: boolean;
     /**
-     * Retention for the transform Lambda's CloudWatch log group (default:
-     * three months / 90 days).
+     * Require the transform Lambda's code asset to carry the `.deployable`
+     * marker a full `build:lambda` writes, proving it has its native sharp
+     * binary. Checked only with `lazyPublicTransforms`. Set `false` ONLY in this
+     * package's own tests, which synth against the `--skip-native` fixture.
+     *
+     * @default true
      */
+    readonly requireDeployableBundle?: boolean;
+    /** Lazy mode only. Retention for the transform Lambda's log group (default 90 days). */
     readonly transformLogRetention?: logs.RetentionDays;
     /**
-     * Concurrency cap on the transform Lambda (default: 10).
-     *
-     * This is a reservation — a CAP carved from the account's concurrency pool,
-     * not pre-warmed capacity, so it costs nothing when idle. It bounds the
-     * blast radius of the anonymous `/assets/t/*` path; see the default
-     * constant's doc comment. Raise it for an unusually image-heavy site;
-     * setting it to 0 would disable transforms entirely.
+     * Lazy mode only. Concurrency cap on the transform Lambda (default 10), a
+     * reservation that costs nothing idle. 0 disables transforms.
      */
     readonly transformReservedConcurrency?: number;
     /**
-     * How long generated derivatives under `assets/t/` are kept (default: 180
-     * days). Only applies to a bucket this construct creates — in BYO-bucket
-     * mode the caller owns lifecycle rules.
-     *
-     * These objects are regenerable; expiry is self-healing (the next request
-     * regenerates and re-stores). Source assets under `asset-originals/` are
-     * never affected.
+     * Lazy mode only. How long the Lambda's `assets/t/` outputs are kept
+     * (default 180 days), written as a lifecycle rule on a bucket this construct
+     * creates. On a BYO `bucket` nothing is written and the prop is required:
+     * passing it states that your bucket expires them itself, filtering on the
+     * tag `canopy-transform=lazy` so what `materialize-assets` writes survives,
+     * and on a versioned bucket also expiring noncurrent versions. Remove that
+     * rule before leaving lazy mode: a key the Lambda wrote first stays tagged
+     * after a build references it. A cross-account bucket's policy must also
+     * grant the transform role `s3:PutObjectTagging` on `assets/t/*`.
      */
     readonly transformOutputRetention?: Duration;
     /**
-     * Execution role for the transform Lambda (default: CDK creates one).
+     * Lazy mode only. Execution role for the transform Lambda (default: CDK creates one).
      *
      * Set this when the role's ARN has to be computable WITHOUT a reference to
      * this construct - the motivating case is an asset bucket in a different AWS
@@ -192,11 +210,10 @@ export interface AssetSupportProps {
      */
     readonly transformRole?: iam.Role;
     /**
-     * Name for the transform Lambda's CloudWatch log group (default:
+     * Lazy mode only. Name for the transform Lambda's CloudWatch log group (default:
      * `/canopycms/<stackName>/transform`). Deliberately NOT
-     * `/aws/lambda/<function-name>` - see `transformLogGroup`'s comment in the
-     * constructor for why a CDK-managed group must avoid that exact name once
-     * the function has ever been deployed without one. Override to follow an
+     * `/aws/lambda/<function-name>` - see the log group's comment in
+     * `buildTransformLambda` for why. Override to follow an
      * org naming convention, or when instantiating this construct twice in one
      * stack (the default name would collide).
      */
@@ -249,10 +266,8 @@ export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "as
  * ```ts
  * const behaviors = assetSupport.assetBehaviors()
  *
- * // CloudFront matches path patterns in the order listed and stops at the
- * // first match, so the more specific '/assets/t/*' MUST come before
- * // '/assets/*' - otherwise the broader S3-only pattern swallows transform
- * // requests and they 403 with no Lambda fallback.
+ * // CloudFront stops at the first matching pattern, so '/assets/t/*' MUST
+ * // come before '/assets/*', or lazy mode's misses never reach the Lambda.
  * new cloudfront.Distribution(this, 'Dist', {
  *   defaultBehavior: ...,
  *   additionalBehaviors: {
@@ -264,18 +279,13 @@ export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "as
  */
 export interface AssetCloudFrontBehaviors {
     /**
-     * `/assets/*` - static objects only (sanitized SVG/PDF the finalize
-     * pipeline wrote, plus already-computed transform outputs under
-     * `assets/t/...`, which also live under this prefix). S3 origin only -
-     * nothing here is ever computed on demand.
+     * `/assets/*`: the S3 read origin (an origin group with `replicaBucket`).
      */
     readonly assets: cloudfront.BehaviorOptions;
     /**
-     * `/assets/t/*` - transform outputs specifically. Origin group: the same
-     * S3 origin as `assets` primary, falling over to the transform Lambda's
-     * Function URL on 403 OR 404 (a signed OAC origin reports a miss as 403;
-     * configuring both is defense-in-depth). CloudFront caches the failover
-     * response.
+     * `/assets/t/*`: the same read origin as `assets`, or with
+     * `lazyPublicTransforms` an origin group falling over to the transform
+     * Lambda on 403 or 404.
      */
     readonly assetsTransform: cloudfront.BehaviorOptions;
 }
@@ -312,15 +322,8 @@ export interface AssetUploadBehaviorRouteOptions extends AssetUploadBehaviorOpti
  * ```
  *
  * Separate from `AssetSupport.uploadBehavior()` because the upload route needs
- * the bucket and nothing else, while that construct's CONSTRUCTOR always builds
- * the transform Lambda, a log group, a Function URL, a role and prefix grants.
- * Those grants never reach the BUCKET policy: `Grant.addToPrincipalOrResource`
- * stops after the identity statement for a same-account grantee, and
- * `addToResourcePolicy` on a bucket CDK does not own is a no-op - an owned
- * bucket, one imported by name, and one imported by ARN in another account all
- * emit zero `AWS::S3::BucketPolicy`, so a cross-account adopter writes the
- * resource half on the bucket's own side. Prefer the method when you already
- * have an `AssetSupport`; both funnel into the same builder and cannot drift.
+ * the bucket and nothing else. Prefer the method when you already have an
+ * `AssetSupport`; both funnel into the same builder and cannot drift.
  *
  * No bucket CORS rule is written and none is needed: the edge supplies
  * `Access-Control-Allow-Origin`, and S3's ACCEPTANCE of a presigned POST is
@@ -336,12 +339,12 @@ export declare function assetUploadBehavior(scope: Construct, options: AssetUplo
  * Wires:
  *
  * - The bucket's asset-prefix lifecycle rule + CORS (standalone mode only).
- * - The transform Lambda (`../../lambda/asset-transform/handler.ts`, built
- *   via `pnpm run build:lambda` - see that script's doc comment for the
- *   no-Docker sharp bundling approach), its dedicated CloudWatch log group
- *   (custom name/retention/removal policy instead of the
- *   CloudFormation-implicit `/aws/lambda/<function-name>` group), and its
- *   OAC-locked Function URL.
+ * - The public read path: `/assets/*` and `/assets/t/*` served from S3 (plus
+ *   `replicaBucket` on 5xx). It computes nothing; derivatives come from
+ *   `canopycms materialize-assets`.
+ * - With `lazyPublicTransforms`, the transform Lambda
+ *   (`../../lambda/asset-transform/handler.ts`, built by `build:lambda`), its
+ *   log group and its OAC-locked Function URL, behind `/assets/t/*`.
  * - `attachTo(distribution)`, which attaches the two CloudFront behaviors a
  *   consuming distribution needs in the only safe order (see its doc comment
  *   for why the order is the whole point); `assetBehaviors()` is the escape
@@ -356,11 +359,12 @@ export declare function assetUploadBehavior(scope: Construct, options: AssetUplo
 export declare class AssetSupport extends Construct {
     /** The bucket in use (either created here, or the BYO `props.bucket`). */
     readonly bucket: s3.IBucket;
-    readonly transformFunction: lambda.Function;
-    /** The transform Lambda's CloudWatch log group (Lambda stdout/stderr). */
-    readonly transformLogGroup: logs.LogGroup;
-    /** The transform Lambda's Function URL - use as a CloudFront origin (see `assetBehaviors()`). */
-    readonly transformFunctionUrl: lambda.FunctionUrl;
+    /** The lazy transform Lambda; undefined unless `lazyPublicTransforms`. */
+    readonly transformFunction: lambda.Function | undefined;
+    /** The transform Lambda's CloudWatch log group; undefined unless `lazyPublicTransforms`. */
+    readonly transformLogGroup: logs.LogGroup | undefined;
+    /** The transform Lambda's Function URL; undefined unless `lazyPublicTransforms`. */
+    readonly transformFunctionUrl: lambda.FunctionUrl | undefined;
     /** Effective advisory upload-size cap (see `AssetSupportProps.maxUploadBytes`). */
     readonly maxUploadBytes: number;
     private readonly behaviors;
@@ -388,6 +392,7 @@ export declare class AssetSupport extends Construct {
      */
     private uploadOrigin?;
     constructor(scope: Construct, id: string, props: AssetSupportProps);
+    private buildTransformLambda;
     private buildBehaviors;
     /**
      * The two CloudFront behavior configs this system needs.
@@ -424,9 +429,8 @@ export declare class AssetSupport extends Construct {
      *   site's cookies and any cached basic-auth credential are live hazards
      *   there, stripped by policy and function rather than never sent at all.
      * - NOT one shared distribution serving asset reads AND writes for every
-     *   environment. That means one `AssetSupport`, which owns the transform
-     *   Lambda shipping inside this package, so a `canopycms-cdk` bump would move
-     *   every environment's asset pipeline at once. Only the upload route moves;
+     *   environment. That means one `AssetSupport`, so a `canopycms-cdk` bump
+     *   would move every environment's asset pipeline at once. Only the upload route moves;
      *   it depends on the bucket and nothing else, the same property that lets
      *   `assetUploadBehavior` build it from a bucket alone.
      */
@@ -435,17 +439,12 @@ export declare class AssetSupport extends Construct {
      * Attach both asset behaviors to a concrete CloudFront distribution, in the
      * only safe order.
      *
-     * THE ORDER IS THE WHOLE POINT. CloudFront matches path patterns in the order
-     * given and stops at the first match. `/assets/*` is a broader, S3-only
-     * pattern that also matches every `/assets/t/*` request; `/assets/t/*` is an
-     * origin group that fails over to the transform Lambda on a miss. Attach
-     * `/assets/*` first and every never-yet-computed transform gets a permanent
-     * 403 (an OAC-signed S3 miss reports 403) while already-computed transforms
-     * keep working. `'/assets/*'` also sorts BEFORE `'/assets/t/*'`
-     * lexicographically (`*` = 0x2A, `t` = 0x74), so alphabetizing the keys
-     * reproduces exactly this failure with no synth or deploy error to catch it -
-     * and `assetBehaviors()` attaches no path pattern, so nothing there stops a
-     * caller getting it wrong.
+     * CloudFront stops at the first matching pattern, and `/assets/*` also
+     * matches every `/assets/t/*` request. With `lazyPublicTransforms`, attaching
+     * it first means no miss ever reaches the transform Lambda, with no synth or
+     * deploy error; `'/assets/*'` also sorts first alphabetically. The two
+     * behaviors are identical otherwise, and the order is kept so that switching
+     * modes changes nothing else.
      *
      * `overrides` is merged into BOTH behaviors. The motivating case is a
      * distribution running a viewer-request function on every behavior - tier