canopycms-cdk 0.0.67-int.90 → 0.0.67-int.91

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

@@ -11,15 +11,13 @@ export interface AssetUploadBehaviorOptions {
      * this behavior alone.
      *
      * `['*']` by default, and a wildcard is defensible HERE in a way a
-     * bucket-wide CORS rule is not, because **the edge authorises nothing**:
-     * measured, a presigned POST with a corrupted signature sent through this
-     * exact path returns 403 and nothing lands. Authority is entirely the
-     * presigned policy, which pins the bucket, the exact key, the content type,
-     * a size range and a 15-minute expiry. So the wildcard widens who may READ
-     * the response, not who may write - and the response is an empty 204.
-     *
-     * Narrow it to your editor origin(s) if you would rather; nothing else here
-     * depends on the wildcard.
+     * bucket-wide CORS rule is not, because **the edge authorises nothing**: a
+     * presigned POST with a corrupted signature sent through this exact path
+     * returns 403 and nothing lands. Authority is entirely the presigned policy,
+     * which pins the bucket, the exact key, the content type, a size range and a
+     * 15-minute expiry. So the wildcard widens who may READ the response, not who
+     * may write - and the response is an empty 204. Narrow it to your editor
+     * origin(s) if you would rather; nothing else here depends on it.
      *
      * ORIGINS ARE MATCHED EXACTLY, and `'*'` is honoured only as the sole entry.
      * CloudFront's response headers policy would accept a leftmost-subdomain
@@ -58,12 +56,10 @@ export interface AssetSupportProps {
      * `Access-Control-Allow-Origin` from the edge instead, so no bucket rule is
      * written and no exact origin has to be named anywhere.
      *
-     * Optional since that edge route exists - it was required while the bucket
-     * rule was the only route. Standalone mode still refuses to synth with
-     * NEITHER, because the resulting failure is a genuinely misleading one (see
-     * the error's own text). An empty array counts as absent: CloudFormation
-     * rejects a CORS rule with no origins, so it can only ever have been a
-     * mistake.
+     * Optional, but standalone mode refuses to synth with NEITHER, because the
+     * resulting failure is a genuinely misleading one (see the error's own text).
+     * An empty array counts as absent: CloudFormation rejects a CORS rule with no
+     * origins, so it can only ever have been a mistake.
      *
      * @default - no bucket CORS rule; standalone mode then requires `uploadBehavior`
      */
@@ -71,37 +67,30 @@ export interface AssetSupportProps {
     /**
      * Build a CloudFront behavior that accepts the editor's presigned-POST
      * uploads - the infrastructure half of `media.uploadUrl` (see the README's
-     * "Routing uploads through your own CDN"). Retrieve the result with
-     * `uploadBehavior()`, which also documents the distribution it belongs on.
-     *
-     * OFF unless set, and deliberately so: this is the only thing in this
+     * "Routing uploads through your own CDN"). Retrieve it with
+     * `uploadBehavior()`, which documents the distribution it belongs on. OFF
+     * unless set, and deliberately so: this is the only thing in this
      * construct that puts a write-capable, OAC-UNSIGNED origin in front of the
-     * bucket, and that must never appear in a template by accident. Pass
-     * `uploadBehavior: {}` to take the defaults.
-     *
-     * BYO-BUCKET CAVEATS - three, and the first is about your bucket policy:
-     *
-     * 1. YOUR BUCKET POLICY IS THE ONLY GATE ON THIS ROUTE. The read behaviors
-     *    reach the bucket through an OAC-SIGNED origin, so a permissive policy
-     *    there is still gated by a signature CloudFront adds. This origin cannot
-     *    be signed (CloudFront never hashes the body, so an OAC-signed origin
-     *    rejects every multipart POST), so nothing gates it but the policy. The
-     *    route is contained by rewriting every request to `/`, which leaves an
-     *    anonymous caller only the bucket-level operations at the root - so what
-     *    your policy grants anonymously AT THE BUCKET ROOT is what is reachable.
-     *    A bucket this construct creates refuses all of them (BLOCK_ALL, no
-     *    public policy); an existing bucket is yours to have got right, and "the
-     *    read path already works" is not evidence that it is.
-     * 2. This origin addresses the bucket by `bucketRegionalDomainName`, and for
-     *    a bucket imported with `Bucket.fromBucketName()` that resolves to the
-     *    STACK's region, not the bucket's. The read path tolerates a mismatch
-     *    because CloudFront follows S3's region redirect on an S3-type origin;
-     *    this one is a custom origin and does not, so S3's 301 reaches the
-     *    browser, where a redirected cross-origin POST surfaces as an opaque
-     *    network error. Import a cross-region bucket with
-     *    `Bucket.fromBucketAttributes({ region })` so the domain name is right.
-     * 3. A DOT in the bucket name breaks this origin specifically - refused at
-     *    synth, with the reason, in `buildUploadBehavior`.
+     * bucket, and that must never reach a template by accident. Pass
+     * `uploadBehavior: {}` for the defaults. BYO-BUCKET CAVEATS:
+     *
+     * 1. YOUR BUCKET POLICY IS THE ONLY GATE ON THIS ROUTE. The read behaviors go
+     *    through an OAC-SIGNED origin, so a permissive policy there is still
+     *    gated by a signature CloudFront adds; this origin cannot be signed
+     *    (CloudFront never hashes the body, so an OAC-signed origin rejects every
+     *    multipart POST). The route is contained by rewriting every request to
+     *    `/`, so what your policy grants anonymously AT THE BUCKET ROOT is what is
+     *    reachable. A bucket this construct creates refuses all of it (BLOCK_ALL,
+     *    no public policy); an existing one is yours, and a read path that already
+     *    works is not evidence that it is right.
+     * 2. This origin addresses the bucket by `bucketRegionalDomainName`, which for
+     *    a bucket imported with `Bucket.fromBucketName()` resolves to the STACK's
+     *    region, not the bucket's. The read path tolerates a mismatch because
+     *    CloudFront follows S3's region redirect on an S3-type origin; this custom
+     *    origin does not, so S3's 301 reaches the browser as an opaque network
+     *    error. Import cross-region with `Bucket.fromBucketAttributes({ region })`.
+     * 3. A DOT in the bucket name breaks this origin; `buildUploadBehavior`
+     *    refuses it at synth, with the reason.
      *
      * @default - no upload behavior is built
      */
@@ -144,12 +133,11 @@ export interface AssetSupportProps {
      * `build:lambda`). Leave this ON for anything that can reach a real
      * deploy.
      *
-     * Set to `false` ONLY in this package's own tests, which deliberately
-     * synth against the cheap `--skip-native` fixture bundle that
-     * `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` back in front of every test
-     * run (which is what kept these tests out of CI in the first place).
+     * 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.
      *
      * Adopters never need this: the published package's asset is built by
      * `prepack`'s full `build:lambda`, so the marker is always present.
@@ -186,26 +174,21 @@ export interface AssetSupportProps {
      * 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 case that motivated the prop is an asset bucket in a
-     * different AWS account from the compute, where the resource-policy half of
-     * the cross-account grant must be written in the bucket's own stack and needs
-     * the principal as a plain string. Reading `transformFunction.role` across an
+     * this construct - the motivating case is an asset bucket in a different AWS
+     * account from the compute, where the resource-policy half of the
+     * cross-account grant is written in the bucket's own stack and needs the
+     * principal as a plain string. Reading `transformFunction.role` across an
      * account boundary does not give you that: CDK emits `Fn::GetStackOutput`, a
-     * CDK-CLI-only intrinsic resolved at deploy time, so the coupling is
-     * invisible to CloudFormation and unusable by any deploy path that is not
-     * `cdk deploy`. Create a deterministically NAMED role instead and both stacks
-     * can compute `arn:aws:iam::<account>:role/<name>` from literals, with
-     * nothing crossing between them.
-     *
-     * A named IAM role means the consuming stack needs `CAPABILITY_NAMED_IAM`,
-     * and cannot be replaced in place without a rename - that trade is yours to
-     * make here, which is the point of taking a role rather than a name.
+     * CDK-CLI-only intrinsic resolved at deploy time, so the coupling is invisible
+     * to CloudFormation and unusable by any deploy path that is not `cdk deploy`.
+     * A deterministically NAMED role lets both stacks compute
+     * `arn:aws:iam::<account>:role/<name>` from literals instead, with nothing
+     * crossing between them - at the cost of `CAPABILITY_NAMED_IAM` in the
+     * consuming stack and no in-place replacement without a rename.
      *
      * `iam.Role`, not `iam.IRole`, ON PURPOSE - an imported role silently
      * discards the managed policies this construct has to re-attach. See
-     * `attachLambdaExecutionPolicies` (./lambda-execution-role) for what CDK
-     * drops when a role is passed, and why the narrower type is what makes the
-     * compensation reliable.
+     * `attachLambdaExecutionPolicies` (./lambda-execution-role).
      */
     readonly transformRole?: iam.Role;
     /**
@@ -240,15 +223,13 @@ export declare const ASSETS_TRANSFORM_PATH_PATTERN: string;
  * instead. Exported so `cms-distribution.ts`'s synth-time guard can
  * recognize the mistake and name it in its error.
  *
- * `uploadBehavior()` deliberately adds NO key here, considered and rejected
- * when it was added. It returns a bare `BehaviorOptions` rather than a named
- * property of a returned object, so there is no spread to get wrong in the
- * first place - and a speculative `'upload'` entry would actively misfire on
- * an adopter whose distribution has a real upload route, since CloudFront
- * treats a path pattern's leading slash as optional and `upload` is a legal
- * spelling of `/upload` (see `normalizePathPattern` in cms-distribution.ts).
- * Keep this list to property names that actually exist on
- * `AssetCloudFrontBehaviors`.
+ * `uploadBehavior()` deliberately adds NO key here: it returns a bare
+ * `BehaviorOptions` rather than a named property, so there is no spread to get
+ * wrong, and a speculative `'upload'` entry would misfire on an adopter whose
+ * distribution has a real upload route - CloudFront treats a path pattern's
+ * leading slash as optional, so `upload` is a legal spelling of `/upload` (see
+ * `normalizePathPattern` in cms-distribution.ts). Keep this list to property
+ * names that actually exist on `AssetCloudFrontBehaviors`.
  */
 export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "assetsTransform"];
 /**
@@ -257,29 +238,21 @@ export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "as
  * (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.
+ * `assetSupport` prop over consuming this directly - both encode the required
+ * attachment order in exactly one place, and the latter's synth-time guard
+ * rejects the three ways manual wiring goes wrong (see
+ * `assertNoAssetBehaviorOrderingHazards`). This value is the ESCAPE HATCH for a
+ * bespoke `new cloudfront.Distribution(...)` assembled entirely inline, whose
+ * `additionalBehaviors` is fixed at construction with no distribution yet to
+ * call `addBehavior` on - there you own the ordering:
  *
  * ```ts
  * const behaviors = assetSupport.assetBehaviors()
  *
- * // 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.
+ * // 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.
  * new cloudfront.Distribution(this, 'Dist', {
  *   defaultBehavior: ...,
  *   additionalBehaviors: {
@@ -301,9 +274,8 @@ export interface AssetCloudFrontBehaviors {
      * `/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). See the SPIKE RESULT in
-     * `.claude/future-tasks/assets-media-system.md` - this design is
-     * confirmed working with CloudFront caching the failover response.
+     * configuring both is defense-in-depth). CloudFront caches the failover
+     * response.
      */
     readonly assetsTransform: cloudfront.BehaviorOptions;
 }
@@ -339,82 +311,28 @@ export interface AssetUploadBehaviorRouteOptions extends AssetUploadBehaviorOpti
  * // media.uploadUrl = `https://${uploads.distributionDomainName}/`
  * ```
  *
- * WHY THIS EXISTS SEPARATELY FROM `AssetSupport.uploadBehavior()`. The upload
- * route depends on the bucket and nothing else, which is what lets it live on
- * its own one-route distribution (the topology `AssetSupport.uploadBehavior()`
- * documents and recommends). But `AssetSupport`'s CONSTRUCTOR builds the
- * transform Lambda unconditionally, and with it a log group, a Function URL, a
- * role, and `grantRead`/`grantPut` on three prefixes. Reaching the upload
- * behavior through the class therefore costs an instantiation whose only
- * purpose is to be instantiated.
- *
- * That footprint is cheaper than it looks, and the reason is worth stating
- * because the opposite is easy to assume: those grants do NOT land in the
- * bucket policy. `Grant.addToPrincipalOrResource` (aws-cdk-lib,
- * `aws-iam/lib/grant.ts`) adds the identity statement first and returns right
- * there when two things hold - the identity statement was actually added, AND
- * the grantee's account is known to match the resource's (`TokenComparison`
- * SAME, or both unresolved). Only when one of those fails does it also write a
- * resource statement. A same-account Lambda with a CDK-managed role satisfies
- * both, so its grants go to that function's OWN execution role and nowhere
- * else. Measured on a synthesized template, an owned bucket plus a
- * same-account `AssetSupport` emits no `AWS::S3::BucketPolicy` at all.
- * Deleting the construct therefore takes the whole footprint with it and
- * leaves nothing behind on a shared bucket's policy.
- *
- * Nor does the cross-account shape invert it, which is the obvious next
- * guess and is also wrong. Measured across all three shapes - an owned
- * bucket, one imported by name, and one imported by ARN with an explicitly
- * DIFFERENT account - every one emits zero `AWS::S3::BucketPolicy`. The
- * second half of `addToPrincipalOrResource` does run for an import, but
- * `addToResourcePolicy` on a bucket CDK does not own is a no-op: it cannot
- * write a policy onto a resource it did not create. So a cross-account
- * adopter gets the identity half here and writes the resource half
- * themselves, on the bucket's own side.
- *
- * What it costs instead is legibility: a second `AssetSupport` standing in a
- * stack that has no asset pipeline, existing only so that a method can be
- * called on it, is fine on the day and unexplainable six months later. That
- * is what this function removes, and it matters most for the shape the
- * one-route topology invites - one bucket shared by every environment, owned
- * by a stack that holds no per-environment resources, with reads and
- * transforms staying per-environment.
- *
- * `AssetSupport.uploadBehavior()` remains the right call when you already have
- * an `AssetSupport`; both funnel into the same builder, so the two cannot
- * drift.
- *
- * TWO THINGS TO KNOW ABOUT `scope`. It receives the CloudFront Function and
- * the two policies as children under fixed ids, so calling this twice with
- * the SAME scope throws CDK's duplicate-construct-id error rather than
- * returning a second behavior - one call per scope. And because the children
- * hang off `scope`, moving an EXISTING deployment from
- * `AssetSupport.uploadBehavior()` to this function changes their construct
- * path and therefore their logical IDs, which replaces all three CloudFront
- * resources. There is no reason to make that move on a stack that already has
- * an `AssetSupport`; this function is for the stack that would otherwise have
- * to grow one.
- *
- * TWO THINGS THIS DOES NOT DO, both deliberate:
+ * 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.
  *
- * - It writes NO bucket CORS rule, and needs none. The edge supplies
- *   `Access-Control-Allow-Origin`; S3's acceptance of a presigned POST and its
- *   ADVERTISEMENT of CORS are independent, and only the second is what a
- *   bucket CORS rule governs. `AssetSupportProps.editorOrigins` is the prop
- *   that writes one, and it belongs to the construct, not to this route.
- * - It registers no synth-time guard for "built but never attached to a
- *   distribution". `AssetSupport` has one, but it fires only in standalone
- *   mode with no `editorOrigins` - where opting into `uploadBehavior` is what
- *   satisfied the "something must supply ACAO" guard, so opting in and
- *   stopping leaves a bucket with neither. A caller here always brings their
- *   own bucket and never passes through that guard, so there is no invariant
- *   to protect: a discarded return value is an obviously unfinished call, not
- *   a silently broken one.
+ * 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
+ * independent of its ADVERTISEMENT of CORS, which is all a bucket rule governs
+ * (`AssetSupportProps.editorOrigins` writes one, for the construct). No
+ * "built but never attached" guard either: a caller here brings their own
+ * bucket, so never reaches the construct's "something must supply ACAO" guard.
  */
 export declare function assetUploadBehavior(scope: Construct, options: AssetUploadBehaviorRouteOptions): cloudfront.BehaviorOptions;
 /**
  * Per-site CDK construct for the asset/media delivery system (see
- * `.claude/future-tasks/assets-media-system.md` for the full design record).
+ * `.claude/future-tasks/resolved/assets-media-system.md` for the full design record).
  * Wires:
  *
  * - The bucket's asset-prefix lifecycle rule + CORS (standalone mode only).
@@ -438,7 +356,6 @@ 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;
-    /** The transform Lambda function. */
     readonly transformFunction: lambda.Function;
     /** The transform Lambda's CloudWatch log group (Lambda stdout/stderr). */
     readonly transformLogGroup: logs.LogGroup;
@@ -453,14 +370,12 @@ export declare class AssetSupport extends Construct {
      * Memoized on the first `uploadBehavior()` call, NOT built in the
      * constructor. Opting in creates three CloudFront resources (function,
      * origin request policy, response headers policy) and response headers
-     * policies have a default account quota of 20 - so an adopter who sets the
+     * policies have a default account quota of 20, so an adopter who sets the
      * prop on a per-environment `AssetSupport` while building the single shared
      * upload distribution the accessor recommends would otherwise mint a set per
-     * environment for one route. Deferring is invisible other than in what gets
-     * emitted, with one exception worth knowing rather than discovering: calling
-     * the accessor AFTER a synth has run modifies the construct tree, and CDK
-     * refuses that with `ConstructTreeModifiedAfterSynth` naming the constructs
-     * added. Loud, not silent.
+     * environment for one route. Deferring is invisible except that calling the
+     * accessor AFTER a synth has run modifies the construct tree, which CDK
+     * refuses with `ConstructTreeModifiedAfterSynth`. Loud, not silent.
      */
     private upload?;
     /**
@@ -477,17 +392,13 @@ export declare class AssetSupport extends Construct {
     /**
      * The two CloudFront behavior configs this system needs.
      *
-     * If you use this rather than `attachTo` -- which takes an `overrides`
-     * parameter, so needing per-behavior options is not a reason to fall back
-     * here -- you own the ordering, and you should assert it: read the
-     * SYNTHESIZED template's `CacheBehaviors` array index, not your own source
-     * object, since the property is about emitted order.
-     *
-     * 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.
+     * Prefer `attachTo(distribution)` or `CanopyCmsDistribution`'s `assetSupport`
+     * prop, which attach these in the only safe order automatically; `attachTo`
+     * takes an `overrides` parameter, so needing per-behavior options is not a
+     * reason to fall back here. Use this only for a distribution assembled
+     * entirely by hand - you then own the ordering, and should assert it against
+     * the SYNTHESIZED template's `CacheBehaviors` array index rather than your own
+     * source object, since the property is about emitted order.
      */
     assetBehaviors(): AssetCloudFrontBehaviors;
     /**
@@ -503,95 +414,52 @@ export declare class AssetSupport extends Construct {
      * })
      * // media.uploadUrl = `https://${uploads.distributionDomainName}/`
      * ```
-     *
-     * No custom domain or certificate is needed - the `d111...cloudfront.net`
-     * name is a perfectly good `uploadUrl` - and as the default behavior of a
-     * one-route distribution there is no path pattern and so no ordering
-     * question of the kind `attachTo()` exists to settle.
-     *
-     * Two shapes this deliberately is NOT, both settled 2026-09-11 (the record
-     * is `.claude/future-tasks/resolved/asset-support-upload-behavior.md`):
-     *
-     * - NOT a behavior on the site's own distribution. `CustomErrorResponses`
-     *   are distribution-wide, so a site that maps 403 to its own 404 page
-     *   applies that to S3's upload errors too and the editor reports the
-     *   substituted status. The site's cookies and any cached basic-auth
-     *   credential are also live hazards there that have to be stripped by
-     *   policy and function (`buildUploadBehavior` removes both - cookies via
-     *   the origin request policy, `Authorization` in the viewer-request
-     *   function) rather than simply never
-     *   being sent. It works; it is just strictly worse.
+     * No custom domain or certificate is needed, and as the default behavior of a
+     * one-route distribution there is no path pattern, so no ordering question of
+     * the kind `attachTo()` settles. Two shapes this deliberately is NOT:
+     *
+     * - NOT a behavior on the site's own distribution. `CustomErrorResponses` are
+     *   distribution-wide, so a site mapping 403 to its own 404 page applies that
+     *   to S3's upload errors and the editor reports the substituted status; the
+     *   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. One assets distribution means one `AssetSupport`, and
-     *   `AssetSupport` owns the transform Lambda - so it would also mean one
-     *   transform Lambda shared by every environment, and that Lambda ships
-     *   inside this package. A `canopycms-cdk` bump would then move every
-     *   environment's asset pipeline at once, which is a graduated rollout
-     *   traded away for an upload path. Reads and transforms stay
-     *   per-environment; only the upload route moves.
-     *
-     * The upload route is the one part of this system with no per-environment
-     * code in it - it depends on the bucket and nothing else - which is why it
-     * is the part that can be split off this way.
-     *
-     * That same property is why `assetUploadBehavior` exists as a free function:
-     * it builds this behavior from a bucket alone, for a caller who wants the
-     * one-route distribution above and has no other use for an `AssetSupport`.
-     * Prefer this method when you already have one; both funnel into the same
-     * builder. See that function for what instantiating the construct purely to
-     * reach this method actually costs.
+     *   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;
+     *   it depends on the bucket and nothing else, the same property that lets
+     *   `assetUploadBehavior` build it from a bucket alone.
      */
     uploadBehavior(): cloudfront.BehaviorOptions;
     /**
      * 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.
-     *
-     * `overrides` is merged into BOTH behaviors, and exists because without it
-     * this method is unusable by exactly the adopters who most need the ordering
-     * guarantee. A distribution that runs a viewer-request function on every
-     * behavior - tier basic-auth, most commonly - needs the asset behaviors to
-     * carry that same `functionAssociations`, or `/assets/*` is anonymously
-     * readable on an authenticated tier. Before this parameter existed such an
-     * adopter had to fall back to `assetBehaviors()` plus two hand-ordered
-     * `addBehavior` calls: the precise shape this method was added to eliminate,
-     * re-entered while believing ordering was handled upstream, which is worse
-     * than never having had the method. (`responseHeadersPolicy` is the same
-     * story for a repo with a shared security-headers policy.)
-     *
-     * Merged into both rather than per-behavior on purpose: applying one set to
-     * both is what preserves the ordering guarantee as the only thing this
-     * method decides. A caller who genuinely needs the two behaviors to differ
-     * has left this method's remit and should use `assetBehaviors()` - and keep
-     * their own ordering assertion.
-     *
-     * Typed `Partial<AddBehaviorOptions>`, not `BehaviorOptions`, because
-     * `addBehavior` takes `origin` positionally - so an `origin` key here would be
-     * a silently ignored no-op. (Measured: passing one changes nothing in the
-     * emitted template. It is a confusing no-op being prevented, not a broken
-     * origin group.)
-     *
-     * 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.
+     * 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.
+     *
+     * `overrides` is merged into BOTH behaviors. The motivating case is a
+     * distribution running a viewer-request function on every behavior - tier
+     * basic-auth - where without the same `functionAssociations` `/assets/*` is
+     * anonymously readable on an authenticated tier (`responseHeadersPolicy` is
+     * the same story for a shared security-headers policy). One set for both is
+     * what keeps ordering the only thing this method decides; a caller who needs
+     * the two to differ should use `assetBehaviors()` and assert their own order.
+     *
+     * Typed `Partial<AddBehaviorOptions>`, not `BehaviorOptions`: `addBehavior`
+     * takes `origin` positionally, so an `origin` key here is a silent no-op. It
+     * needs a concrete `cloudfront.Distribution` too - `addBehavior` is an
+     * instance method on that class, not on `IDistribution`. For a distribution
+     * built entirely inline, call `assetBehaviors()` and order it yourself.
      */
     attachTo(distribution: cloudfront.Distribution, overrides?: Partial<cloudfront.AddBehaviorOptions>): void;
     /**