canopycms-cdk 0.0.66-int.81 → 0.0.66-int.83

package/dist/constructs/asset-support.d.ts

@@ -107,16 +107,54 @@ export interface AssetSupportProps {
      */
     readonly transformLogGroupName?: string;
 }
+/**
+ * The two CloudFront path patterns the asset system's behaviors are keyed
+ * under, derived from `PREFIXES` above (the single source of truth for these
+ * prefixes in this file) rather than spelled out again. Exported so
+ * `cms-distribution.ts`'s synth-time ordering guard can recognize them
+ * without a second, driftable copy of the literal strings.
+ */
+export declare const ASSETS_PATH_PATTERN: string;
+export declare const ASSETS_TRANSFORM_PATH_PATTERN: string;
+/**
+ * The literal property names of `AssetCloudFrontBehaviors`
+ * (`assets`/`assetsTransform`). It is a natural but broken mistake to spread
+ * `assetBehaviors()`'s return value directly into `additionalBehaviors` (a
+ * `Record<pathPattern, BehaviorOptions>`) - that type-checks and deploys
+ * clean, but synthesizes two CloudFront behaviors matching the literal path
+ * patterns `assets` and `assetsTransform`, which nothing ever requests,
+ * instead of the real `/assets/*` and `/assets/t/*` patterns. Use
+ * `attachTo()` (below) or `CanopyCmsDistribution`'s `assetSupport` prop
+ * instead. Exported so `cms-distribution.ts`'s synth-time guard can
+ * recognize the mistake and name it in its error.
+ */
+export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "assetsTransform"];
 /**
  * The two CloudFront behavior configs the asset system needs, keyed by the
  * path pattern they belong under. Each value is a full `BehaviorOptions`
- * (origin included), so a consumer can use it either way:
+ * (origin included).
+ *
+ * Prefer `AssetSupport.attachTo(distribution)` or `CanopyCmsDistribution`'s
+ * `assetSupport` prop over consuming this directly - both encode the
+ * required attachment order in exactly one place instead of asking every
+ * caller to reproduce it correctly. This return value remains useful as an
+ * ESCAPE HATCH for a bespoke `new cloudfront.Distribution(...)` assembled
+ * entirely inline (its `additionalBehaviors` is fixed at construction, so
+ * there is no distribution yet to call `addBehavior` on) - but manual use
+ * must still preserve the ordering shown below, and
+ * `CanopyCmsDistribution`'s synth-time guard (`mergeBehaviors`) actively
+ * rejects three ways this goes wrong: `/assets/*` listed before
+ * `/assets/t/*`; the literal keys `assets`/`assetsTransform` (see
+ * `ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS`) from spreading this object directly
+ * into a `Record`; or an asset pattern listed here at all while
+ * `CanopyCmsDistribution`'s `assetSupport` prop is also passed. See
+ * `assertNoAssetBehaviorOrderingHazards`'s doc comment for the full list.
  *
  * ```ts
  * const behaviors = assetSupport.assetBehaviors()
  *
- * // Building a new distribution. CloudFront matches path patterns in the
- * // order they're listed and stops at the first match, so the more
+ * // Building a new distribution inline. CloudFront matches path patterns in
+ * // the order they're 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 first and they
  * // 403 with no Lambda fallback.
@@ -127,12 +165,6 @@ export interface AssetSupportProps {
  *     '/assets/*': behaviors.assets,
  *   },
  * })
- *
- * // Adding to an existing distribution: the same first-match-wins ordering
- * // applies to the resulting CacheBehaviors list, so call addBehavior for
- * // '/assets/t/*' before '/assets/*' here too.
- * distribution.addBehavior('/assets/t/*', behaviors.assetsTransform.origin, behaviors.assetsTransform)
- * distribution.addBehavior('/assets/*', behaviors.assets.origin, behaviors.assets)
  * ```
  */
 export interface AssetCloudFrontBehaviors {
@@ -165,9 +197,11 @@ export interface AssetCloudFrontBehaviors {
  *   (custom name/retention/removal policy instead of the
  *   CloudFormation-implicit `/aws/lambda/<function-name>` group), and its
  *   OAC-locked Function URL.
- * - `assetBehaviors()`, the two CloudFront behavior configs a consuming
- *   distribution attaches (see `AssetCloudFrontBehaviors`'s doc comment for
- *   both attachment shapes).
+ * - `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
+ *   hatch for a distribution built entirely by hand (see
+ *   `AssetCloudFrontBehaviors`'s doc comment).
  * - `grantUploadAccess()`, the exact prefix-scoped grants the CMS/editor
  *   principal needs to run `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts).
  */
@@ -183,10 +217,48 @@ export declare class AssetSupport extends Construct {
     /** Effective advisory upload-size cap (see `AssetSupportProps.maxUploadBytes`). */
     readonly maxUploadBytes: number;
     private readonly behaviors;
+    /** Distributions `attachTo` has already wired -- see that method's duplicate check. */
+    private readonly attachedDistributions;
     constructor(scope: Construct, id: string, props: AssetSupportProps);
     private buildBehaviors;
-    /** The two CloudFront behavior configs this system needs - see `AssetCloudFrontBehaviors`'s doc comment for both attachment shapes. */
+    /**
+     * The two CloudFront behavior configs this system needs.
+     *
+     * Prefer `attachTo(distribution)` or `CanopyCmsDistribution`'s
+     * `assetSupport` prop, which attach these to a distribution in the only
+     * safe order automatically. This method exists as the escape hatch for a
+     * distribution assembled entirely by hand - see `AssetCloudFrontBehaviors`'s
+     * doc comment for that shape and its ordering requirements.
+     */
     assetBehaviors(): AssetCloudFrontBehaviors;
+    /**
+     * Attach both asset behaviors to a concrete CloudFront distribution, in the
+     * only safe order.
+     *
+     * THIS METHOD EXISTS BECAUSE THE ORDER IS THE WHOLE POINT.
+     * `assetBehaviors()` returns `{ assets, assetsTransform }` with no path
+     * pattern attached at all (see that method's and `AssetCloudFrontBehaviors`'s
+     * doc comments) - so nothing stops a caller from attaching the two in
+     * either order. 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 - silent, launch-delayed, and permanent.
+     * `'/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.
+     *
+     * Needs a concrete `cloudfront.Distribution` - `addBehavior` is an instance
+     * method on that class, not on `IDistribution` (what an imported/looked-up
+     * distribution reference gives you). For a distribution built entirely
+     * inline (its `additionalBehaviors` fixed at construction, with no
+     * distribution yet to call `addBehavior` on), call `assetBehaviors()`
+     * directly instead and list `/assets/t/*` before `/assets/*` yourself - see
+     * `AssetCloudFrontBehaviors`'s doc comment.
+     */
+    attachTo(distribution: cloudfront.Distribution): void;
     /**
      * Grant the CMS/editor principal (the CMS Lambda's role, typically) the
      * exact permissions `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts)

package/dist/constructs/asset-support.js

@@ -111,6 +111,28 @@ const TRANSFORM_OUTPUT_RETENTION = Duration.days(180);
 const TRANSFORM_CACHE_MIN_TTL = Duration.seconds(0);
 const TRANSFORM_CACHE_DEFAULT_TTL = Duration.days(1);
 const TRANSFORM_CACHE_MAX_TTL = Duration.days(365);
+/**
+ * The two CloudFront path patterns the asset system's behaviors are keyed
+ * under, derived from `PREFIXES` above (the single source of truth for these
+ * prefixes in this file) rather than spelled out again. Exported so
+ * `cms-distribution.ts`'s synth-time ordering guard can recognize them
+ * without a second, driftable copy of the literal strings.
+ */
+export const ASSETS_PATH_PATTERN = `/${PREFIXES.public}/*`;
+export const ASSETS_TRANSFORM_PATH_PATTERN = `/${PREFIXES.transform}/*`;
+/**
+ * The literal property names of `AssetCloudFrontBehaviors`
+ * (`assets`/`assetsTransform`). It is a natural but broken mistake to spread
+ * `assetBehaviors()`'s return value directly into `additionalBehaviors` (a
+ * `Record<pathPattern, BehaviorOptions>`) - that type-checks and deploys
+ * clean, but synthesizes two CloudFront behaviors matching the literal path
+ * patterns `assets` and `assetsTransform`, which nothing ever requests,
+ * instead of the real `/assets/*` and `/assets/t/*` patterns. Use
+ * `attachTo()` (below) or `CanopyCmsDistribution`'s `assetSupport` prop
+ * instead. Exported so `cms-distribution.ts`'s synth-time guard can
+ * recognize the mistake and name it in its error.
+ */
+export const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS = ['assets', 'assetsTransform'];
 /**
  * Per-site CDK construct for the asset/media delivery system (see
  * `.claude/future-tasks/assets-media-system.md` for the full design record).
@@ -123,15 +145,19 @@ const TRANSFORM_CACHE_MAX_TTL = Duration.days(365);
  *   (custom name/retention/removal policy instead of the
  *   CloudFormation-implicit `/aws/lambda/<function-name>` group), and its
  *   OAC-locked Function URL.
- * - `assetBehaviors()`, the two CloudFront behavior configs a consuming
- *   distribution attaches (see `AssetCloudFrontBehaviors`'s doc comment for
- *   both attachment shapes).
+ * - `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
+ *   hatch for a distribution built entirely by hand (see
+ *   `AssetCloudFrontBehaviors`'s doc comment).
  * - `grantUploadAccess()`, the exact prefix-scoped grants the CMS/editor
  *   principal needs to run `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts).
  */
 export class AssetSupport extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
+        /** Distributions `attachTo` has already wired -- see that method's duplicate check. */
+        this.attachedDistributions = new WeakSet();
         // Fail closed before anything else: refuse to build a stack around a
         // transform Lambda whose code asset was never verified to contain the
         // linux/arm64 sharp binary. Without this, `pnpm test` (whose
@@ -317,10 +343,67 @@ export class AssetSupport extends Construct {
         };
         return { assets, assetsTransform };
     }
-    /** The two CloudFront behavior configs this system needs - see `AssetCloudFrontBehaviors`'s doc comment for both attachment shapes. */
+    /**
+     * The two CloudFront behavior configs this system needs.
+     *
+     * Prefer `attachTo(distribution)` or `CanopyCmsDistribution`'s
+     * `assetSupport` prop, which attach these to a distribution in the only
+     * safe order automatically. This method exists as the escape hatch for a
+     * distribution assembled entirely by hand - see `AssetCloudFrontBehaviors`'s
+     * doc comment for that shape and its ordering requirements.
+     */
     assetBehaviors() {
         return this.behaviors;
     }
+    /**
+     * Attach both asset behaviors to a concrete CloudFront distribution, in the
+     * only safe order.
+     *
+     * THIS METHOD EXISTS BECAUSE THE ORDER IS THE WHOLE POINT.
+     * `assetBehaviors()` returns `{ assets, assetsTransform }` with no path
+     * pattern attached at all (see that method's and `AssetCloudFrontBehaviors`'s
+     * doc comments) - so nothing stops a caller from attaching the two in
+     * either order. 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 - silent, launch-delayed, and permanent.
+     * `'/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.
+     *
+     * Needs a concrete `cloudfront.Distribution` - `addBehavior` is an instance
+     * method on that class, not on `IDistribution` (what an imported/looked-up
+     * distribution reference gives you). For a distribution built entirely
+     * inline (its `additionalBehaviors` fixed at construction, with no
+     * distribution yet to call `addBehavior` on), call `assetBehaviors()`
+     * directly instead and list `/assets/t/*` before `/assets/*` yourself - see
+     * `AssetCloudFrontBehaviors`'s doc comment.
+     */
+    attachTo(distribution) {
+        // `addBehavior` does not dedupe, and these calls bypass
+        // `CanopyCmsDistribution`'s own synth-time guard because they run after
+        // that distribution is constructed. So attaching twice -- passing the
+        // `assetSupport` prop AND calling this yourself, most likely, since the
+        // prop's doc comment describes them as equivalent -- synthesizes
+        // ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'] and fails at
+        // deploy time when CloudFront rejects the duplicate patterns. Refuse it
+        // here instead, where the message can say which two routes collided.
+        if (this.attachedDistributions.has(distribution)) {
+            throw new Error(`AssetSupport: attachTo() was already called for this distribution. Each pattern ` +
+                `would be attached twice and CloudFront rejects duplicate path patterns at deploy ` +
+                `time. This usually means the distribution was given CanopyCmsDistribution's ` +
+                `\`assetSupport\` prop (which calls attachTo for you) as well as an explicit ` +
+                `attachTo() call -- keep one.`);
+        }
+        this.attachedDistributions.add(distribution);
+        const { origin: transformOrigin, ...transformRest } = this.behaviors.assetsTransform;
+        const { origin: assetsOrigin, ...assetsRest } = this.behaviors.assets;
+        distribution.addBehavior(ASSETS_TRANSFORM_PATH_PATTERN, transformOrigin, transformRest);
+        distribution.addBehavior(ASSETS_PATH_PATTERN, assetsOrigin, assetsRest);
+    }
     /**
      * Grant the CMS/editor principal (the CMS Lambda's role, typically) the
      * exact permissions `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts)

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

@@ -1,5 +1,6 @@
 import { Construct } from 'constructs';
 import { Duration, aws_cloudfront as cloudfront, aws_certificatemanager as acm, aws_route53 as route53, aws_lambda as lambda } from 'aws-cdk-lib';
+import type { AssetSupport } from './asset-support.js';
 export interface CanopyCmsDistributionProps {
     /** Lambda Function URL from CanopyCmsService */
     functionUrl: lambda.FunctionUrl;
@@ -49,8 +50,39 @@ export interface CanopyCmsDistributionProps {
      * overridden key takes YOUR position in this object, not the position the
      * default held. (A plain object spread would do the opposite; see
      * `mergeBehaviors`.)
+     *
+     * Prefer the `assetSupport` prop over wiring `AssetSupport`'s behaviors in
+     * here by hand — but if you do it by hand anyway, `mergeBehaviors` throws
+     * at synth if it sees any of the three AssetSupport footguns: `/assets/*`
+     * listed before `/assets/t/*`; the literal keys `assets`/`assetsTransform`
+     * (from spreading `assetBehaviors()`'s return value directly into this
+     * object instead of keying it by path pattern); or an asset pattern listed
+     * here at all while the `assetSupport` prop is also passed (see that
+     * prop's own doc comment). See `assertNoAssetBehaviorOrderingHazards`'s
+     * doc comment for the full list.
      */
     additionalBehaviors?: Record<string, cloudfront.BehaviorOptions>;
+    /**
+     * Attach `AssetSupport`'s CloudFront behaviors (`/assets/*` and
+     * `/assets/t/*`) to the distribution this construct builds, in the only
+     * safe order - see `AssetSupport.attachTo()`'s doc comment for why the
+     * order matters. Equivalent to calling
+     * `assetSupport.attachTo(distribution)` yourself right after construction,
+     * but with nothing to forget.
+     *
+     * Prefer this over passing `assetSupport.assetBehaviors()` through
+     * `additionalBehaviors` by hand - that stays available as an escape hatch
+     * (e.g. for behaviors that are not from `AssetSupport` at all), and this
+     * construct's synth-time guard (`mergeBehaviors`) still checks it for the
+     * three ways that manual wiring is known to go wrong: see
+     * `additionalBehaviors`'s own doc comment.
+     *
+     * No ordering logic lives in this construct beyond calling this method -
+     * ordering is encoded exactly once, in `AssetSupport.attachTo()` itself.
+     *
+     * @default - no asset behaviors are attached
+     */
+    assetSupport?: AssetSupport;
 }
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
@@ -66,6 +98,8 @@ export interface CanopyCmsDistributionProps {
  * - Cache policies: no-cache for /api/* and /edit*, cache /_next/static/*
  * - Viewer-request CloudFront Function setting x-forwarded-host (redirect-URL
  *   derivation behind the Host-stripping OAC origin)
+ * - `AssetSupport`'s `/assets/*` and `/assets/t/*` behaviors, in the required
+ *   order, when the `assetSupport` prop is passed
  */
 export declare class CanopyCmsDistribution extends Construct {
     /** The CloudFront distribution */

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 { 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
  * ordering for every key they supply.
@@ -16,11 +17,105 @@ import { DEFAULT_CMS_LAMBDA_TIMEOUT, MAX_CLOUDFRONT_ORIGIN_READ_TIMEOUT } from '
  * Dropping collided defaults FIRST means the caller's own object contributes
  * its keys in its own order.
  */
-function mergeBehaviors(defaults, caller) {
+function mergeBehaviors(defaults, caller, attachingAssetSupport) {
     if (!caller)
         return defaults;
     const uncollided = Object.fromEntries(Object.entries(defaults).filter(([pattern]) => !(pattern in caller)));
-    return { ...uncollided, ...caller };
+    const merged = { ...uncollided, ...caller };
+    assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport);
+    return merged;
+}
+/**
+ * Guards against the three AssetSupport CloudFront-behavior hazards a manually
+ * assembled `additionalBehaviors` can introduce (see
+ * `AssetSupport.attachTo()`'s doc comment for the full mechanism):
+ *
+ * 1. The literal keys `assets`/`assetsTransform` present in `merged` mean
+ *    `assetSupport.assetBehaviors()`'s return value was spread directly into
+ *    `additionalBehaviors` (a `Record<pathPattern, BehaviorOptions>`) instead
+ *    of being attached via `assetSupport.attachTo(distribution)` or this
+ *    construct's `assetSupport` prop. This type-checks and deploys clean,
+ *    synthesizing two behaviors matching the literal path patterns `assets`
+ *    and `assetsTransform`, which nothing ever requests.
+ * 2. `/assets/*` listed before `/assets/t/*` means CloudFront's first-match-
+ *    wins ordering serves every transform request off the broader, S3-only
+ *    `/assets/*` behavior, permanently 403ing any derivative that has not
+ *    already been computed (an OAC-signed S3 miss reports 403).
+ * 3. Either asset pattern present in `merged` WHILE the `assetSupport` prop is
+ *    also passed means both wiring routes are active at once, so each pattern
+ *    is attached twice. This is the migration mistake specifically - keeping a
+ *    hand-wired block while adopting the prop - and hazard 2 cannot catch it,
+ *    because the hand-written order is usually the correct one.
+ *
+ * `Object.keys` insertion order is spec-guaranteed for string keys like
+ * these (none are integer-like array-index strings), so comparing index
+ * order here is sound.
+ *
+ * SCOPE LIMIT: this protects only callers going through
+ * `CanopyCmsDistribution`'s own `additionalBehaviors` merge. It cannot help a
+ * bespoke `new cloudfront.Distribution(...)` assembled elsewhere -
+ * `AssetSupport.attachTo()` is the answer there.
+ */
+/**
+ * CloudFront treats the leading `/` on a path pattern as optional -- `assets/*`
+ * and `/assets/*` match exactly the same requests, and AWS's own console and
+ * docs frequently show the slash-less spelling. The checks below therefore
+ * compare NORMALIZED keys: without this, writing `{ 'assets/*': ..., 'assets/t/*': ... }`
+ * walked past all three hazards and synthesized the broad-pattern-first order
+ * this guard exists to refuse -- silently, which is the worst of the failure
+ * modes here.
+ */
+function normalizePathPattern(pattern) {
+    return pattern.startsWith('/') ? pattern.slice(1) : pattern;
+}
+function assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport) {
+    const keys = Object.keys(merged).map(normalizePathPattern);
+    const assetsPattern = normalizePathPattern(ASSETS_PATH_PATTERN);
+    const transformPattern = normalizePathPattern(ASSETS_TRANSFORM_PATH_PATTERN);
+    const spreadMistakeKeys = ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS.filter((key) => key in merged);
+    if (spreadMistakeKeys.length > 0) {
+        throw new Error(`CanopyCmsDistribution: additionalBehaviors has literal key(s) ` +
+            `${spreadMistakeKeys.map((k) => JSON.stringify(k)).join(', ')}, which is not a ` +
+            `CloudFront path pattern. This usually means assetSupport.assetBehaviors()'s return ` +
+            `value was spread directly into additionalBehaviors instead of attached via ` +
+            `assetSupport.attachTo(distribution) or this construct's \`assetSupport\` prop - either ` +
+            `of which attaches the real '${ASSETS_PATH_PATTERN}' and '${ASSETS_TRANSFORM_PATH_PATTERN}' ` +
+            `path patterns in the required order.`);
+    }
+    // Both halves wired at once. `attachTo` runs AFTER the distribution is
+    // constructed, so its `addBehavior` calls never pass through this function -
+    // meaning a caller who keeps a hand-wired asset block AND adopts the
+    // `assetSupport` prop gets each pattern attached twice. Measured: CDK does
+    // not object, and synthesizes CacheBehaviors
+    // ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'], which CloudFront
+    // then rejects at deploy time for the duplicate path patterns. That is a
+    // late failure of exactly the kind this guard exists to convert into a synth
+    // one, and it is the most likely mistake during migration: the correct
+    // hand-written order does NOT trip the check below, so nothing else would
+    // catch it.
+    if (attachingAssetSupport) {
+        const alsoWiredByHand = [ASSETS_PATH_PATTERN, ASSETS_TRANSFORM_PATH_PATTERN].filter((pattern) => keys.includes(normalizePathPattern(pattern)));
+        if (alsoWiredByHand.length > 0) {
+            throw new Error(`CanopyCmsDistribution: the \`assetSupport\` prop attaches ` +
+                `'${ASSETS_TRANSFORM_PATH_PATTERN}' and '${ASSETS_PATH_PATTERN}' itself, but ` +
+                `additionalBehaviors already lists ${alsoWiredByHand.map((p) => `'${p}'`).join(' and ')}. ` +
+                `Each pattern would be attached twice and CloudFront rejects duplicate path patterns at ` +
+                `deploy time. Remove the asset entries from additionalBehaviors and keep the ` +
+                `\`assetSupport\` prop, which also guarantees the required order.`);
+        }
+    }
+    const assetsIndex = keys.indexOf(assetsPattern);
+    const transformIndex = keys.indexOf(transformPattern);
+    if (assetsIndex !== -1 && transformIndex !== -1 && assetsIndex < transformIndex) {
+        throw new Error(`CanopyCmsDistribution: additionalBehaviors lists '${ASSETS_PATH_PATTERN}' before ` +
+            `'${ASSETS_TRANSFORM_PATH_PATTERN}'. CloudFront matches path patterns in the order given ` +
+            `and stops at the first match, so every '${ASSETS_TRANSFORM_PATH_PATTERN}' request would ` +
+            `be served by the broader, S3-only '${ASSETS_PATH_PATTERN}' behavior and never fail over ` +
+            `to the transform Lambda - a permanent 403 on any derivative that has not already been ` +
+            `computed. List '${ASSETS_TRANSFORM_PATH_PATTERN}' first, or use ` +
+            `assetSupport.attachTo(distribution) / this construct's \`assetSupport\` prop, which get ` +
+            `the order right automatically.`);
+    }
 }
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.
@@ -36,6 +131,8 @@ function mergeBehaviors(defaults, caller) {
  * - Cache policies: no-cache for /api/* and /edit*, cache /_next/static/*
  * - Viewer-request CloudFront Function setting x-forwarded-host (redirect-URL
  *   derivation behind the Host-stripping OAC origin)
+ * - `AssetSupport`'s `/assets/*` and `/assets/t/*` behaviors, in the required
+ *   order, when the `assetSupport` prop is passed
  */
 export class CanopyCmsDistribution extends Construct {
     constructor(scope, id, props) {
@@ -160,8 +257,15 @@ export class CanopyCmsDistribution extends Construct {
                     cachePolicy: staticCachePolicy,
                     viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
                 },
-            }, props.additionalBehaviors),
+            }, props.additionalBehaviors, props.assetSupport !== undefined),
         });
+        // Attach AssetSupport's behaviors (if provided), in the only safe order -
+        // see AssetSupport.attachTo()'s doc comment. This is the ONLY place this
+        // construct deals with the asset behaviors' ordering; the actual ordering
+        // logic lives exactly once, inside attachTo() itself. Callers who instead
+        // pass `assetSupport.assetBehaviors()` through `additionalBehaviors` by
+        // hand are covered by `mergeBehaviors`'s synth-time guard above instead.
+        props.assetSupport?.attachTo(this.distribution);
         // ========================================================================
         // DNS Records
         // ========================================================================

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

@@ -72,8 +72,57 @@ export interface CanopyCmsServiceProps {
     githubTokenSecretArn?: string;
     /** Secrets Manager ARN for the Clerk secret key */
     clerkSecretKeySecretArn?: string;
-    /** Base branch name (default: 'main') */
+    /**
+     * The GitHub repository's default branch name (default: 'main').
+     *
+     * Interpolated straight into a git ref (`refs/heads/{baseBranch}`) and into
+     * the worker's `.env` heredoc, so an invalid value is rejected at synth (see
+     * `assertValidGitBranchName` above) instead of deploying an instance that
+     * boots successfully and then fails. And fail it will, permanently:
+     * `verifyBaseBranchExists`
+     * (packages/canopycms/src/worker/cms-worker.ts) throws when the named branch
+     * does not exist in the cloned `remote.git`, `start()`'s catch records the
+     * fatal error, `worker/index.ts` exits 1, and systemd's `Restart=always`
+     * repeats that forever — there is no working worker at all until the value
+     * is fixed and the instance replaced, and `rebaseActiveBranches` fetches and
+     * rebases against the wrong lineage in the meantime.
+     *
+     * MUST match the shared repo's `canopycms.config.ts`'s `defaultBaseBranch`
+     * (both default to 'main' when unset) — the two are resolved by different
+     * processes (this stamps the worker's `.env`; the Lambda reads
+     * `config.defaultBaseBranch` at request time) with no automatic
+     * reconciliation between them. `infrastructure/lib/cms-stack.ts`, as
+     * scaffolded by `canopycms init-deploy aws`, derives this prop FROM that same
+     * config file at synth time so the two cannot drift for adopters who deploy
+     * through the generated stack; a hand-rolled stack must set this explicitly
+     * whenever `defaultBaseBranch` is anything other than 'main'.
+     */
     baseBranch?: string;
+    /**
+     * Explicit settings-branch name, stamped into the worker's
+     * `CANOPYCMS_SETTINGS_BRANCH` environment variable (default: unset, in which
+     * case the worker falls through to the same computed name the Lambda uses,
+     * `canopycms-settings-<deploymentName>` — see `deploymentName` below).
+     *
+     * Only set this to mirror an adopter-configured `config.settingsBranch` in
+     * `canopycms.config.ts`. Leaving both unset (the default) is safe: Lambda and
+     * worker then resolve the SAME computed name independently, with nothing to
+     * keep in sync. But if the shared config sets `settingsBranch` explicitly
+     * and this prop is left unset, the worker keeps resolving the computed name
+     * while the Lambda's `getSettingsBranchName` short-circuits on
+     * `config.settingsBranch` — so the two own different branches. The PRIMARY
+     * settings-push path still reaches GitHub (its task payload carries the
+     * Lambda-resolved name), but the worker's per-cycle backstop push
+     * (`pushSettingsBranches`) targets the wrong branch and its "foreign settings
+     * branch" [SYNC-M3] warning misfires against the deployment's own branch.
+     * Validated at synth like `baseBranch` (see `assertValidGitBranchName`),
+     * since this is interpolated into a git ref and the worker's `.env` heredoc
+     * too. `infrastructure/lib/cms-stack.ts`, as scaffolded by
+     * `canopycms init-deploy aws`, derives this prop from the same
+     * `canopycms.config.ts` at synth time, so the two cannot drift for adopters
+     * who deploy through the generated stack.
+     */
+    settingsBranch?: string;
     /**
      * Deployment name (default: 'prod'). Namespaces the settings branch
      * (`canopycms-settings-{deploymentName}`) so this stack's CMS Lambda/worker