canopycms-cdk 0.0.66-int.86 → 0.0.67-int.88

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

@@ -79,14 +79,29 @@ export interface AssetSupportProps {
      * bucket, and that must never appear in a template by accident. Pass
      * `uploadBehavior: {}` to take the defaults.
      *
-     * BYO-BUCKET CAVEAT: 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.
+     * 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`.
      *
      * @default - no upload behavior is built
      */
@@ -292,6 +307,111 @@ export interface AssetCloudFrontBehaviors {
      */
     readonly assetsTransform: cloudfront.BehaviorOptions;
 }
+/**
+ * Options for `assetUploadBehavior` - everything
+ * `AssetSupportProps.uploadBehavior` accepts, plus the bucket that the
+ * standalone form has no construct to read it from.
+ */
+export interface AssetUploadBehaviorRouteOptions extends AssetUploadBehaviorOptions {
+    /**
+     * The bucket presigned uploads land in.
+     *
+     * ALWAYS the BYO case, and the caveat that goes with it is real: this
+     * behavior's origin is deliberately OAC-UNSIGNED (it has to be - see
+     * `buildUploadBehavior`), so this bucket's own policy is the only thing
+     * standing between an anonymous caller and whatever that policy allows at
+     * `/`. The URI rewrite means nothing arriving here can address a key, so
+     * that is bucket-level operations only, and a bucket with BLOCK_ALL and no
+     * public policy refuses all of them - but it is the bucket policy doing the
+     * refusing, not this construct.
+     */
+    readonly bucket: s3.IBucket;
+}
+/**
+ * The presigned-upload CloudFront behavior, built from a bucket alone - the
+ * infrastructure half of `media.uploadUrl` for callers who have a bucket and
+ * no use for an `AssetSupport`.
+ *
+ * ```ts
+ * const uploads = new cloudfront.Distribution(this, 'AssetUploads', {
+ *   defaultBehavior: assetUploadBehavior(this, { bucket: assetBucket }),
+ * })
+ * // 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:
+ *
+ * - 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.
+ */
+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).
@@ -343,19 +463,23 @@ export declare class AssetSupport extends Construct {
      * added. Loud, not silent.
      */
     private upload?;
-    constructor(scope: Construct, id: string, props: AssetSupportProps);
-    private buildBehaviors;
     /**
-     * The behavior that accepts the editor's presigned-POST uploads. Every piece
-     * below is load-bearing; see `uploadBehavior()` for where the result goes.
+     * The origin inside `upload`, kept so the validation below can ask whether
+     * that behavior was ever attached to a distribution - see `UploadOrigin`.
+     * Set by `uploadBehavior()`, i.e. at the same moment as `upload`: the
+     * builder is shared with `assetUploadBehavior`, which has no construct to
+     * record anything on, so recovering the origin from the returned behavior is
+     * this class's job rather than the builder's.
      */
-    private buildUploadBehavior;
+    private uploadOrigin?;
+    constructor(scope: Construct, id: string, props: AssetSupportProps);
+    private buildBehaviors;
     /**
      * The two CloudFront behavior configs this system needs.
      *
-     * If you use this rather than `attachTo` -- which now takes an `overrides`
-     * parameter, so needing per-behavior options is no longer a reason to fall
-     * back here -- you own the ordering, and you should assert it: read the
+     * 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.
      *
@@ -409,6 +533,13 @@ export declare class AssetSupport extends Construct {
      * 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.
      */
     uploadBehavior(): cloudfront.BehaviorOptions;
     /**
@@ -448,14 +579,11 @@ export declare class AssetSupport extends Construct {
      * has left this method's remit and should use `assetBehaviors()` - and keep
      * their own ordering assertion.
      *
-     * Typed `Partial<AddBehaviorOptions>` because that is exactly what
-     * `addBehavior(pattern, origin, behaviorOptions?)` accepts - `origin` is a
-     * POSITIONAL argument there, so `BehaviorOptions` (which is
-     * `AddBehaviorOptions` plus `origin`) would let a caller pass a key the call
-     * silently ignores. Measured, because the first version of this comment
-     * claimed the opposite: widening the parameter and passing an `origin`
-     * override changes nothing in the emitted template, so this narrowing
-     * prevents a confusing no-op rather than a broken origin group.
+     * 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

package/dist/constructs/asset-support.js

@@ -32,17 +32,11 @@ const transformAssetDir = path.join(__dirname, '..', '..', 'lambda', 'asset-tran
  */
 const DEPLOYABLE_MARKER = '.deployable';
 /**
- * The four S3 key prefixes the asset system uses, mirrored from
- * `packages/canopycms/src/assets/asset-prefixes.ts` (the source of truth).
- * Duplicated as plain string literals - not imported from `canopycms` -
- * because this construct must synth cleanly for ANY consumer's CDK app
- * (e.g. a site's own `infrastructure/` package), which has no reason to
- * have `canopycms` itself resolvable from wherever its CDK code runs. The
- * transform Lambda (../../lambda/asset-transform/handler.ts), by contrast,
- * is bundled at build time from WITHIN this package (where `canopycms` is a
- * real workspace devDependency), so it imports the canonical constants
- * directly from `canopycms/server` instead of duplicating them - see that
- * file's doc comment.
+ * The four S3 key prefixes the asset system uses. Source of truth is
+ * `packages/canopycms/src/assets/asset-prefixes.ts`; these are copied as
+ * literals rather than imported so this construct synths in a consumer CDK app
+ * that has no `canopycms` resolvable. (The transform Lambda does import them -
+ * it is bundled from inside this package; see its handler's doc comment.)
  */
 const PREFIXES = {
     originals: 'asset-originals',
@@ -141,23 +135,64 @@ const TRANSFORM_CACHE_MIN_TTL = Duration.seconds(0);
 const TRANSFORM_CACHE_DEFAULT_TTL = Duration.days(1);
 const TRANSFORM_CACHE_MAX_TTL = Duration.days(365);
 /**
- * Distributions that already carry the asset behaviors, tracked at MODULE level
- * rather than per instance.
+ * Id of the marker construct `attachTo` adds to a distribution to record that
+ * the asset behaviors are already on it.
  *
- * Per-instance (the first version of this) only caught the same `AssetSupport`
- * attaching twice. Two `AssetSupport` constructs attaching to one distribution
- * slipped through and synthesized
- * ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'] - the identical
- * duplicate-path-pattern deploy failure the guard exists to convert into a
- * synth error. There is no legitimate form of that: both instances attach the
- * same two patterns, so the second is always wrong regardless of which
- * construct owns it.
+ * The fact being recorded is "THIS distribution already carries these two
+ * patterns", so it is stored ON that distribution rather than in a module-level
+ * registry. Per-INSTANCE state was the first version and was wrong: two
+ * different `AssetSupport` constructs attaching to one distribution slipped
+ * through and synthesized ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'],
+ * the duplicate-path-pattern deploy failure the guard exists to convert into a
+ * synth error. There is no legitimate form of that - both instances attach the
+ * same two patterns, so the second is always wrong regardless of which construct
+ * owns it - so the check has to be keyed on the distribution, not the attacher.
  *
- * A `WeakSet` keyed on the distribution object, so it holds no reference that
- * would outlive the construct tree and cannot leak across CDK apps in a test
- * process.
+ * A module-level `WeakSet` keyed on the distribution object did that correctly
+ * (a `cloudfront.Distribution` instance belongs to exactly one construct tree,
+ * and `attachTo` takes a concrete instance, so one could never be claimed by a
+ * second CDK app). A child construct is preferred anyway because the scoping is
+ * then a property of the tree rather than something the reader has to reason
+ * about process lifetime to trust - and it is visible in `node.children`, so a
+ * test can assert the guard's state instead of only its error.
+ *
+ * The marker is a bare `Construct`, which emits nothing into the template.
+ */
+const ATTACHED_MARKER_ID = 'CanopyAssetBehaviorsAttached';
+/**
+ * The upload behavior's origin, which records having been bound to a
+ * distribution.
+ *
+ * This exists so the synth-time validation below can tell "`uploadBehavior()`
+ * was CALLED" from "its result actually reached a distribution" - two states a
+ * memoized accessor cannot distinguish on its own, and the second is the one
+ * that determines whether anything supplies Access-Control-Allow-Origin.
+ *
+ * CDK calls `bind()` exactly when a `Distribution` takes a behavior: from the
+ * constructor for `defaultBehavior` (the topology `uploadBehavior()`
+ * recommends), and from `addBehavior` for an additional one. Both shapes, and a
+ * distribution in a different stack, are pinned as PASSING cases in
+ * asset-support.test.ts - a mechanism that only sees one of them would fail the
+ * other two at synth. All three bind eagerly at construction, before any
+ * validation runs. A behavior that is built and then dropped never binds.
+ *
+ * Observing the origin rather than searching the tree for the emitted behavior
+ * is what makes the cross-stack case work. Measured: a consuming stack renders
+ * the reference as `Fn::ImportValue`, not as the producing stack's resolved ARN,
+ * so a tree search would report "not attached" for a perfectly correct
+ * cross-stack distribution - a false synth failure, which is worse than the gap
+ * it closes.
  */
-const distributionsWithAssetBehaviors = new WeakSet();
+class UploadOrigin extends origins.HttpOrigin {
+    constructor() {
+        super(...arguments);
+        this.attachedToDistribution = false;
+    }
+    bind(scope, options) {
+        this.attachedToDistribution = true;
+        return super.bind(scope, options);
+    }
+}
 /**
  * The two CloudFront path patterns the asset system's behaviors are keyed
  * under, derived from `PREFIXES` above (the single source of truth for these
@@ -190,6 +225,376 @@ export const ASSETS_TRANSFORM_PATH_PATTERN = `/${PREFIXES.transform}/*`;
  * `AssetCloudFrontBehaviors`.
  */
 export const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS = ['assets', 'assetsTransform'];
+/**
+ * The `allowedOrigins` guards, shared by both entry points.
+ *
+ * These live here rather than inline in `buildUploadBehavior` because
+ * `AssetSupport` runs them in its CONSTRUCTOR - eagerly, long before anything
+ * builds the behavior - and moving them to the builder would delay the throw
+ * to the first `uploadBehavior()` call. `assetUploadBehavior` has no such
+ * split and runs them on entry. One implementation, two call sites, so the
+ * standalone form cannot quietly accept what the construct refuses.
+ *
+ * `label` is the options path to name in the message, so each caller's error
+ * points at the property the caller actually wrote.
+ */
+function validateUploadBehaviorOptions(options, label) {
+    // An empty `allowedOrigins` is the same class of mistake as an empty
+    // `editorOrigins` and gets the same treatment: CloudFormation rejects
+    // `AccessControlAllowOrigins` with no items, so silently falling back to
+    // the `['*']` default would turn a forwarded-empty-env-var into either a
+    // failed deploy or, worse, a wildcard the caller did not ask for.
+    if (options.allowedOrigins?.length === 0) {
+        throw new Error(`${label} is an empty array. CloudFront requires at ` +
+            'least one origin, and defaulting an explicitly-empty list to the wildcard would ' +
+            "silently widen what you asked for. Omit the property to take the `['*']` default, " +
+            'or list the origin(s) the editor is served from.');
+    }
+    // Two consumers read `allowedOrigins` and they do not share a matcher: the
+    // response headers policy (which decides ACAO on the POST response) accepts
+    // CloudFront's pattern grammar, including a leftmost-subdomain wildcard
+    // like `https://*.preview.example.com`; the preflight responder compiled
+    // into the CloudFront Function can only do exact-string comparison, because
+    // reimplementing that grammar in an edge function without being able to
+    // test it against CloudFront is how the two silently disagree.
+    //
+    // So a pattern is refused rather than half-honoured. Accepting one would
+    // deploy clean and then fail every upload from a matching origin at the
+    // PREFLIGHT, with a correct-looking policy sitting right next to it - the
+    // same invisible failure the preflight responder was added to remove.
+    const wildcardOrigins = (options.allowedOrigins ?? []).filter((origin) => origin.includes('*'));
+    const isBareWildcard = options.allowedOrigins?.join() === '*';
+    if (wildcardOrigins.length > 0 && !isBareWildcard) {
+        throw new Error(`${label} contains a wildcard pattern ` +
+            `(${wildcardOrigins.map((o) => JSON.stringify(o)).join(', ')}). CloudFront's response ` +
+            `headers policy would accept it, but the CORS preflight is answered at the edge by a ` +
+            `CloudFront Function that compares origins exactly - so every upload from a matching ` +
+            `origin would fail its preflight while the policy looked correct. Use exactly ` +
+            `['*'] to allow any origin, or list each editor origin in full.`);
+    }
+}
+/**
+ * The behavior that accepts the editor's presigned-POST uploads. Every piece
+ * below is load-bearing; see `assetUploadBehavior` and
+ * `AssetSupport.uploadBehavior()` for where the result goes.
+ *
+ * `label` prefixes the one error raised here, so the message names whichever
+ * entry point the caller used.
+ */
+function buildUploadBehavior(scope, options, label) {
+    // A DISTINCT origin for the bucket, with OAC signing OFF - the read
+    // behaviors' origin cannot be reused here no matter what this behavior
+    // sets, because OAC is a property of the ORIGIN, not the behavior. (On the
+    // dedicated distribution `uploadBehavior()` recommends this is the only
+    // origin present; the point is that it cannot be the read one.)
+    // CloudFront signs origin requests but never hashes
+    // the body, so an OAC-signed origin rejects every multipart POST whatever
+    // the viewer sent. Measured, that is `400 InvalidArgument`, the body
+    // naming the mechanism - `x-amz-content-sha256 must be UNSIGNED-PAYLOAD,
+    // ... or a valid sha256 value`. It fails CLOSED, but it is an
+    // argument-validation error, NOT the 403 that the Lambda Function URL
+    // origin produces in the same situation (docs/deploying-to-aws.md's
+    // "CloudFront OAC and request body signing"): there Lambda verifies a
+    // SIGNATURE over that header, here S3 validates its VALUE FORMAT. An
+    // adopter told to expect 403 goes hunting for a permissions problem that
+    // does not exist.
+    //
+    // `HttpOrigin` rather than `S3BucketOrigin.withBucketDefaults()`, which
+    // would also be unsigned, for two reasons. It is the exact shape this
+    // whole path was measured against end to end on live AWS resources (204,
+    // object landed); and it is the only one of the two that can state the
+    // CloudFront->S3 protocol, which for a request carrying a live upload
+    // credential in its body should be pinned rather than inferred.
+    // `withBucketDefaults()` emits `S3OriginConfig`, which has no
+    // `OriginProtocolPolicy` field at all.
+    // A dot in the bucket name breaks this origin specifically. S3's wildcard
+    // certificate covers one label (`*.s3.<region>.amazonaws.com`), so
+    // `my.docs.bucket.s3.<region>.amazonaws.com` fails TLS validation and
+    // CloudFront answers 502 on every upload. This is a CUSTOM origin doing
+    // ordinary TLS validation; the read path uses an S3-type origin, which
+    // CloudFront treats differently, so nothing else here would surface it -
+    // and dotted names are most likely in exactly the BYO case ("a site's
+    // existing content bucket") this behavior is written for. Only checkable
+    // when the name is a real literal, which for an imported bucket it is.
+    const bucketName = options.bucket.bucketName;
+    if (!Token.isUnresolved(bucketName) && bucketName.includes('.')) {
+        throw new Error(`${label} cannot use bucket "${bucketName}" - a dot in the bucket ` +
+            `name puts an extra label in its regional domain name, which S3's wildcard ` +
+            `certificate does not cover, so CloudFront fails TLS to the origin and answers 502 on ` +
+            `every upload. The read behaviors are unaffected (they use an S3-type origin). Use a ` +
+            `dot-free bucket for uploads, or route uploads somewhere other than this construct.`);
+    }
+    const uploadOrigin = new UploadOrigin(options.bucket.bucketRegionalDomainName, {
+        protocolPolicy: cloudfront.OriginProtocolPolicy.HTTPS_ONLY,
+    });
+    // S3's POST Object is only valid at the bucket ROOT - without this rewrite
+    // the upload gets 405 MethodNotAllowed. It is also what CONTAINS this
+    // behavior: rewriting unconditionally means no request arriving here can
+    // address a key at all, so the `ALLOW_ALL` below buys an anonymous caller
+    // only the bucket-level operations at `/` (list, create, delete bucket).
+    // A bucket this construct creates refuses all of them anonymously
+    // (BLOCK_ALL, no public policy); in BYO-bucket mode that is the caller's
+    // bucket policy to have got right.
+    //
+    // Their bucket policy is a WEAKER backstop here than on the read path, and
+    // the two must not be read as equivalent: the read behaviors go through an
+    // OAC-SIGNED origin, so a too-permissive policy there is still gated by a
+    // signature CloudFront adds. This origin is deliberately unsigned (it has
+    // to be - see the OAC note at the top of this method), so on a BYO bucket
+    // the policy is the ONLY thing standing between an anonymous caller and
+    // whatever that policy allows at `/`. Stated where a BYO adopter reads it,
+    // in `uploadBehavior()`'s caveat block, not only here.
+    //
+    // The only thing that can WRITE either way is a request carrying a valid
+    // presigned policy, and only to the single key that policy names. Do not
+    // make the rewrite conditional; that gives key addressability back.
+    //
+    // The same function also drops `Authorization`. A site behind HTTP basic
+    // auth otherwise sends S3 a credential it cannot parse
+    // (`400 InvalidArgument - Unsupported Authorization Type`), and the
+    // presigned POST carries its own authority in the body, so nothing on this
+    // route ever wants the header. It is dropped HERE, in the function, rather
+    // than by naming it in the origin request policy's `allExcept` list below,
+    // and that placement is deliberate: CloudFront rejects `Authorization` in
+    // an origin request policy's header ALLOWLIST outright ("The parameter
+    // Headers contains Authorization that is not allowed"), and whether the
+    // same validation fires on an `allExcept` list is not something synth can
+    // tell you - it would surface as a failed `cdk deploy` on the whole stack.
+    // A viewer-request function has no such ambiguity: `method` is the only
+    // read-only field on the request object, headers are freely mutable, and
+    // `Authorization` is the header CloudFront's own basic-auth function
+    // examples read. Dropping it at the viewer also means it is gone before
+    // any policy runs, so the guarantee does not depend on the policy at all.
+    // The same function ALSO answers the CORS preflight, and that is not
+    // optional decoration - without it this route cannot work at all.
+    //
+    // The editor's upload is NOT a CORS simple request, though it looks like
+    // one: `xhr-upload.ts` sends multipart/form-data with no custom headers,
+    // but it assigns `xhr.upload.onprogress` before `send()`, and registering
+    // ANY listener on the `XMLHttpRequestUpload` object is its own disqualifier
+    // from the simple-request rules, independent of method, headers and content
+    // type. So every browser upload begins with `OPTIONS /`.
+    //
+    // Nothing else on this route would answer it. CloudFront does not
+    // synthesize preflight responses - a response headers policy supplies
+    // values for headers "in responses to CORS preflight requests", i.e. it
+    // decorates a response that something else produced - and `ALLOW_ALL`
+    // forwards the OPTIONS to S3, which with no CORS configuration answers
+    // `403 CORSResponse: CORS is not enabled for this bucket`. A preflight that
+    // is not a 2xx fails the browser's check whatever headers are attached, so
+    // the POST is never sent and the upload dies as an opaque network error.
+    //
+    // This is why the end-to-end measurements did not catch it: they replayed
+    // the POST as a script, which has no preflight. A scripted POST is not an
+    // acceptance test for this route; a real browser upload is.
+    //
+    // Short-circuiting at the viewer also strengthens the containment argument
+    // above rather than weakening it - an OPTIONS that never reaches the origin
+    // can address nothing.
+    const allowedOrigins = options.allowedOrigins ?? ['*'];
+    const rewriteToBucketRoot = new cloudfront.Function(scope, 'AssetUploadRewriteFunction', {
+        code: cloudfront.FunctionCode.fromInline([
+            `var ALLOWED_ORIGINS = ${toFunctionLiteral(allowedOrigins)};`,
+            'function handler(event) {',
+            '  var request = event.request;',
+            "  if (request.method === 'OPTIONS') {",
+            '    var headers = {',
+            `      'access-control-allow-methods': { value: '${UPLOAD_ALLOWED_METHOD}' },`,
+            "      'access-control-allow-headers': { value: '*' },",
+            `      'access-control-max-age': { value: '${CORS_MAX_AGE_SECONDS}' }`,
+            '    };',
+            // Echo the caller's own Origin when the list is narrowed: a preflight
+            // may only be answered with `*` or the single requesting origin, so a
+            // multi-entry list cannot be returned verbatim. No match means no
+            // ACAO, and the browser's own check refuses the upload - which is the
+            // correct outcome, and a clearer one than a 403 here would be.
+            "    var origin = request.headers.origin ? request.headers.origin.value : '';",
+            "    if (ALLOWED_ORIGINS.length === 1 && ALLOWED_ORIGINS[0] === '*') {",
+            "      headers['access-control-allow-origin'] = { value: '*' };",
+            '    } else if (ALLOWED_ORIGINS.indexOf(origin) !== -1) {',
+            "      headers['access-control-allow-origin'] = { value: origin };",
+            '    }',
+            "    return { statusCode: 204, statusDescription: 'No Content', headers: headers };",
+            '  }',
+            "  request.uri = '/';",
+            '  delete request.headers.authorization;',
+            '  return request;',
+            '}',
+        ].join('\n')),
+    });
+    // `denyList('host')` emits CloudFormation's `allExcept`. In the HEADERS
+    // dimension only, that is the managed ALL_VIEWER_EXCEPT_HOST_HEADER policy
+    // - the shape this path was measured against. It is NOT that policy
+    // overall, and must not be replaced by it: the managed one is documented as
+    // "Cookies: All, Query strings: All", so adopting it would forward the
+    // editor session cookie to S3, which is one of the two hazards this whole
+    // policy exists to remove. Only the header behavior is shared.
+    //
+    // `Authorization` is handled by the function above, not here.
+    //
+    // Cookies go through `CookiesConfig`, not the header list (a CloudFront
+    // Function does not even see them in `request.headers`), so
+    // `cookieBehavior.none()` is what strips them: an upload route mounted on
+    // a site's own distribution would otherwise hand S3 - and S3's access logs
+    // - the editor session cookie. On the dedicated distribution recommended
+    // in `uploadBehavior()` a cross-origin XHR without `withCredentials` sends
+    // none in the first place; this makes it true either way.
+    const originRequestPolicy = new cloudfront.OriginRequestPolicy(scope, 'AssetUploadOriginRequestPolicy', {
+        cookieBehavior: cloudfront.OriginRequestCookieBehavior.none(),
+        headerBehavior: cloudfront.OriginRequestHeaderBehavior.denyList('host'),
+        // A presigned POST carries everything in the multipart body.
+        queryStringBehavior: cloudfront.OriginRequestQueryStringBehavior.none(),
+    });
+    // The edge supplies Access-Control-Allow-Origin, scoped to this behavior
+    // only. This is the measurement that unblocked the whole design: a
+    // response-headers policy DOES attach ACAO to a 2xx from an unsigned S3
+    // origin on POST with NO bucket CORS configuration at all (204, `ACAO: *`,
+    // object landed). Acceptance and advertisement are independent in S3 -
+    // bucket CORS governs only whether S3 advertises - which is exactly the
+    // property that lets this construct avoid writing a bucket CORS rule.
+    //
+    // `originOverride: true` so the header is ours deterministically even on a
+    // bucket that does have its own CORS configuration.
+    //
+    // AllowMethods/AllowHeaders/MaxAge take effect only on a CORS PREFLIGHT,
+    // and this path DOES trigger one - see the CloudFront Function above, which
+    // answers it, and which exists because nothing else would. They are set
+    // here anyway, sharing `UPLOAD_ALLOWED_METHOD` with that function so the
+    // two cannot tell a browser different things, and because a response
+    // headers policy is documented to decorate responses without saying whether
+    // a function-generated one is among them. If it is, `originOverride: true`
+    // means the policy's values REPLACE the function's identical ones; if it is
+    // not, the function's stand alone. Either way the viewer sees exactly one
+    // of each, which is what makes it safe not to know.
+    const responseHeadersPolicy = new cloudfront.ResponseHeadersPolicy(scope, 'AssetUploadResponseHeadersPolicy', {
+        corsBehavior: {
+            accessControlAllowOrigins: allowedOrigins,
+            accessControlAllowCredentials: false,
+            accessControlAllowMethods: [UPLOAD_ALLOWED_METHOD],
+            accessControlAllowHeaders: ['*'],
+            accessControlMaxAge: Duration.seconds(CORS_MAX_AGE_SECONDS),
+            originOverride: true,
+        },
+    });
+    return {
+        origin: uploadOrigin,
+        // A POST is 405 without this. CloudFront offers no narrower set that
+        // includes POST - GET_HEAD, GET_HEAD_OPTIONS and ALL are the only three.
+        // The URI rewrite above is what makes that acceptable.
+        allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
+        // HTTPS_ONLY, NOT the read behaviors' REDIRECT_TO_HTTPS. CloudFront
+        // redirects with 301, and a browser turns a 301'd POST into a GET - so
+        // an `http://` upload URL would silently become a bodyless GET that this
+        // behavior rewrites to `/` and S3 refuses, with the file never sent.
+        // HTTPS_ONLY answers 403 instead: same refusal, visible.
+        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.HTTPS_ONLY,
+        // Nothing on this route is cacheable, and CACHING_DISABLED's all-`none`
+        // cache key is also what keeps the origin request policy above legal
+        // (CloudFront requires it to be a superset of the cache key).
+        cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
+        originRequestPolicy,
+        responseHeadersPolicy,
+        functionAssociations: [
+            {
+                function: rewriteToBucketRoot,
+                eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
+            },
+        ],
+    };
+}
+/**
+ * The presigned-upload CloudFront behavior, built from a bucket alone - the
+ * infrastructure half of `media.uploadUrl` for callers who have a bucket and
+ * no use for an `AssetSupport`.
+ *
+ * ```ts
+ * const uploads = new cloudfront.Distribution(this, 'AssetUploads', {
+ *   defaultBehavior: assetUploadBehavior(this, { bucket: assetBucket }),
+ * })
+ * // 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:
+ *
+ * - 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.
+ */
+export function assetUploadBehavior(scope, options) {
+    validateUploadBehaviorOptions(options, 'assetUploadBehavior: allowedOrigins');
+    // Snapshotted for the same reason `AssetSupport` snapshots it - the guard
+    // above has just read the array, so holding the caller's reference would let
+    // a later `origins.length = 0` walk past a check that already passed. Here
+    // the window is only as long as this call, but the cost of closing it is a
+    // `slice()`.
+    return buildUploadBehavior(scope, { ...options, allowedOrigins: options.allowedOrigins?.slice() }, 'assetUploadBehavior');
+}
 /**
  * Per-site CDK construct for the asset/media delivery system (see
  * `.claude/future-tasks/assets-media-system.md` for the full design record).
@@ -397,39 +802,13 @@ export class AssetSupport extends Construct {
             authType: lambda.FunctionUrlAuthType.AWS_IAM,
         });
         this.behaviors = this.buildBehaviors();
-        // Validated eagerly, built lazily (see `upload`'s comment). An empty
-        // `allowedOrigins` is the same class of mistake as an empty
-        // `editorOrigins` and gets the same treatment: CloudFormation rejects
-        // `AccessControlAllowOrigins` with no items, so silently falling back to
-        // the `['*']` default would turn a forwarded-empty-env-var into either a
-        // failed deploy or, worse, a wildcard the caller did not ask for.
-        if (props.uploadBehavior?.allowedOrigins?.length === 0) {
-            throw new Error('AssetSupport: uploadBehavior.allowedOrigins is an empty array. CloudFront requires at ' +
-                'least one origin, and defaulting an explicitly-empty list to the wildcard would ' +
-                "silently widen what you asked for. Omit the property to take the `['*']` default, " +
-                'or list the origin(s) the editor is served from.');
-        }
-        // Two consumers read `allowedOrigins` and they do not share a matcher: the
-        // response headers policy (which decides ACAO on the POST response) accepts
-        // CloudFront's pattern grammar, including a leftmost-subdomain wildcard
-        // like `https://*.preview.example.com`; the preflight responder compiled
-        // into the CloudFront Function can only do exact-string comparison, because
-        // reimplementing that grammar in an edge function without being able to
-        // test it against CloudFront is how the two silently disagree.
-        //
-        // So a pattern is refused rather than half-honoured. Accepting one would
-        // deploy clean and then fail every upload from a matching origin at the
-        // PREFLIGHT, with a correct-looking policy sitting right next to it - the
-        // same invisible failure the preflight responder was added to remove.
-        const wildcardOrigins = (props.uploadBehavior?.allowedOrigins ?? []).filter((origin) => origin.includes('*'));
-        const isBareWildcard = props.uploadBehavior?.allowedOrigins?.join() === '*';
-        if (wildcardOrigins.length > 0 && !isBareWildcard) {
-            throw new Error(`AssetSupport: uploadBehavior.allowedOrigins contains a wildcard pattern ` +
-                `(${wildcardOrigins.map((o) => JSON.stringify(o)).join(', ')}). CloudFront's response ` +
-                `headers policy would accept it, but the CORS preflight is answered at the edge by a ` +
-                `CloudFront Function that compares origins exactly - so every upload from a matching ` +
-                `origin would fail its preflight while the policy looked correct. Use exactly ` +
-                `['*'] to allow any origin, or list each editor origin in full.`);
+        // Validated eagerly, built lazily (see `upload`'s comment) - the accessor
+        // may never be called, and a bad `allowedOrigins` should not wait for it
+        // to find out. The guards themselves are shared with
+        // `assetUploadBehavior`, which runs them on entry instead; see
+        // `validateUploadBehaviorOptions` for what they refuse and why.
+        if (props.uploadBehavior) {
+            validateUploadBehaviorOptions(props.uploadBehavior, 'AssetSupport: uploadBehavior.allowedOrigins');
         }
         // Snapshotted, not aliased. The guard above runs now but `allowedOrigins`
         // is not READ until the accessor builds the behavior, so holding the
@@ -440,27 +819,45 @@ export class AssetSupport extends Construct {
             allowedOrigins: props.uploadBehavior.allowedOrigins?.slice(),
         };
         // Setting `uploadBehavior` SATISFIES the standalone guard above, but only
-        // calling `uploadBehavior()` and attaching the result actually produces an
+        // ATTACHING the behavior to a distribution actually produces an
         // Access-Control-Allow-Origin from anywhere. Opting in and stopping there -
         // which is exactly what copying the README snippet and not finishing looks
         // like - lands a standalone bucket with no CORS rule and no edge route: the
         // silent failure the guard's own text calls misleading, reached through the
         // guard rather than around it.
         //
+        // The condition is ATTACHMENT, not `uploadBehavior()` having been called.
+        // Those look equivalent and are not: the accessor memoizes, so a caller who
+        // invokes it and loses the value in a refactor sets every flag an accessor
+        // can set and still lands in exactly the state above. That shape is if
+        // anything likelier than never calling it at all, since it is what a
+        // half-finished copy of the README snippet leaves behind. `UploadOrigin`
+        // (above) is what makes the difference observable from here.
+        //
         // A synth-time validation is the only place this can be caught, since the
         // constructor cannot know what the caller will do next. It is the first
         // `addValidation` in this package; the alternative (checking in the
         // constructor) cannot express "and nothing used it".
         this.node.addValidation({
             validate: () => {
-                if (props.uploadBehavior && editorOrigins.length === 0 && !props.bucket && !this.upload) {
+                if (props.uploadBehavior &&
+                    editorOrigins.length === 0 &&
+                    !props.bucket &&
+                    !this.uploadOrigin?.attachedToDistribution) {
                     return [
-                        'AssetSupport: `uploadBehavior` was set but uploadBehavior() was never called, so ' +
-                            'no upload behavior was attached to any distribution and nothing supplies ' +
-                            'Access-Control-Allow-Origin. With no `editorOrigins` either, a browser upload ' +
-                            'will land the object in asset-staging/ and still report a network error. Pass ' +
-                            "the behavior to a distribution (see uploadBehavior()'s doc comment), or pass " +
-                            '`editorOrigins` instead.',
+                        'AssetSupport: `uploadBehavior` was set but the upload behavior was never attached ' +
+                            'to a distribution' +
+                            (this.upload
+                                ? ' - uploadBehavior() was called, but its return value was not passed to one'
+                                : ' - uploadBehavior() was never called') +
+                            ', so nothing supplies Access-Control-Allow-Origin. With no `editorOrigins` ' +
+                            'either, a browser upload will land the object in asset-staging/ and still ' +
+                            'report a network error. Pass the behavior to a distribution (see ' +
+                            "uploadBehavior()'s doc comment), or pass `editorOrigins` instead. If you " +
+                            'built the upload route from this bucket with the `assetUploadBehavior` free ' +
+                            'function, ACAO IS supplied and this check cannot see it - it observes only ' +
+                            'the origin this construct minted. Call uploadBehavior() here instead; you ' +
+                            'already have the construct, so the free function buys you nothing.',
                     ];
                 }
                 return [];
@@ -512,227 +909,12 @@ export class AssetSupport extends Construct {
         };
         return { assets, assetsTransform };
     }
-    /**
-     * The behavior that accepts the editor's presigned-POST uploads. Every piece
-     * below is load-bearing; see `uploadBehavior()` for where the result goes.
-     */
-    buildUploadBehavior(options) {
-        // A DISTINCT origin for the bucket, with OAC signing OFF - the read
-        // behaviors' origin cannot be reused here no matter what this behavior
-        // sets, because OAC is a property of the ORIGIN, not the behavior. (On the
-        // dedicated distribution `uploadBehavior()` recommends this is the only
-        // origin present; the point is that it cannot be the read one.)
-        // CloudFront signs origin requests but never hashes
-        // the body, so an OAC-signed origin rejects every multipart POST whatever
-        // the viewer sent. Measured, that is `400 InvalidArgument`, the body
-        // naming the mechanism - `x-amz-content-sha256 must be UNSIGNED-PAYLOAD,
-        // ... or a valid sha256 value`. It fails CLOSED, but it is an
-        // argument-validation error, NOT the 403 that the Lambda Function URL
-        // origin produces in the same situation (docs/deploying-to-aws.md's
-        // "CloudFront OAC and request body signing"): there Lambda verifies a
-        // SIGNATURE over that header, here S3 validates its VALUE FORMAT. An
-        // adopter told to expect 403 goes hunting for a permissions problem that
-        // does not exist.
-        //
-        // `HttpOrigin` rather than `S3BucketOrigin.withBucketDefaults()`, which
-        // would also be unsigned, for two reasons. It is the exact shape this
-        // whole path was measured against end to end on live AWS resources (204,
-        // object landed); and it is the only one of the two that can state the
-        // CloudFront->S3 protocol, which for a request carrying a live upload
-        // credential in its body should be pinned rather than inferred.
-        // `withBucketDefaults()` emits `S3OriginConfig`, which has no
-        // `OriginProtocolPolicy` field at all.
-        // A dot in the bucket name breaks this origin specifically. S3's wildcard
-        // certificate covers one label (`*.s3.<region>.amazonaws.com`), so
-        // `my.docs.bucket.s3.<region>.amazonaws.com` fails TLS validation and
-        // CloudFront answers 502 on every upload. This is a CUSTOM origin doing
-        // ordinary TLS validation; the read path uses an S3-type origin, which
-        // CloudFront treats differently, so nothing else here would surface it -
-        // and dotted names are most likely in exactly the BYO case ("a site's
-        // existing content bucket") this behavior is written for. Only checkable
-        // when the name is a real literal, which for an imported bucket it is.
-        const bucketName = this.bucket.bucketName;
-        if (!Token.isUnresolved(bucketName) && bucketName.includes('.')) {
-            throw new Error(`AssetSupport: uploadBehavior cannot use bucket "${bucketName}" - a dot in the bucket ` +
-                `name puts an extra label in its regional domain name, which S3's wildcard ` +
-                `certificate does not cover, so CloudFront fails TLS to the origin and answers 502 on ` +
-                `every upload. The read behaviors are unaffected (they use an S3-type origin). Use a ` +
-                `dot-free bucket for uploads, or route uploads somewhere other than this construct.`);
-        }
-        const uploadOrigin = new origins.HttpOrigin(this.bucket.bucketRegionalDomainName, {
-            protocolPolicy: cloudfront.OriginProtocolPolicy.HTTPS_ONLY,
-        });
-        // S3's POST Object is only valid at the bucket ROOT - without this rewrite
-        // the upload gets 405 MethodNotAllowed. It is also what CONTAINS this
-        // behavior: rewriting unconditionally means no request arriving here can
-        // address a key at all, so the `ALLOW_ALL` below buys an anonymous caller
-        // only the bucket-level operations at `/` (list, create, delete bucket).
-        // A bucket this construct creates refuses all of them anonymously
-        // (BLOCK_ALL, no public policy); in BYO-bucket mode that is the caller's
-        // bucket policy to have got right, as it already is for the read path. The
-        // only thing that can WRITE either way is a request carrying a valid
-        // presigned policy, and only to the single key that policy names. Do not
-        // make the rewrite conditional; that gives key addressability back.
-        //
-        // The same function also drops `Authorization`. A site behind HTTP basic
-        // auth otherwise sends S3 a credential it cannot parse
-        // (`400 InvalidArgument - Unsupported Authorization Type`), and the
-        // presigned POST carries its own authority in the body, so nothing on this
-        // route ever wants the header. It is dropped HERE, in the function, rather
-        // than by naming it in the origin request policy's `allExcept` list below,
-        // and that placement is deliberate: CloudFront rejects `Authorization` in
-        // an origin request policy's header ALLOWLIST outright ("The parameter
-        // Headers contains Authorization that is not allowed"), and whether the
-        // same validation fires on an `allExcept` list is not something synth can
-        // tell you - it would surface as a failed `cdk deploy` on the whole stack.
-        // A viewer-request function has no such ambiguity: `method` is the only
-        // read-only field on the request object, headers are freely mutable, and
-        // `Authorization` is the header CloudFront's own basic-auth function
-        // examples read. Dropping it at the viewer also means it is gone before
-        // any policy runs, so the guarantee does not depend on the policy at all.
-        // The same function ALSO answers the CORS preflight, and that is not
-        // optional decoration - without it this route cannot work at all.
-        //
-        // The editor's upload is NOT a CORS simple request, though it looks like
-        // one: `xhr-upload.ts` sends multipart/form-data with no custom headers,
-        // but it assigns `xhr.upload.onprogress` before `send()`, and registering
-        // ANY listener on the `XMLHttpRequestUpload` object is its own disqualifier
-        // from the simple-request rules, independent of method, headers and content
-        // type. So every browser upload begins with `OPTIONS /`.
-        //
-        // Nothing else on this route would answer it. CloudFront does not
-        // synthesize preflight responses - a response headers policy supplies
-        // values for headers "in responses to CORS preflight requests", i.e. it
-        // decorates a response that something else produced - and `ALLOW_ALL`
-        // forwards the OPTIONS to S3, which with no CORS configuration answers
-        // `403 CORSResponse: CORS is not enabled for this bucket`. A preflight that
-        // is not a 2xx fails the browser's check whatever headers are attached, so
-        // the POST is never sent and the upload dies as an opaque network error.
-        //
-        // This is why the end-to-end measurements did not catch it: they replayed
-        // the POST as a script, which has no preflight. A scripted POST is not an
-        // acceptance test for this route; a real browser upload is.
-        //
-        // Short-circuiting at the viewer also strengthens the containment argument
-        // above rather than weakening it - an OPTIONS that never reaches the origin
-        // can address nothing.
-        const allowedOrigins = options.allowedOrigins ?? ['*'];
-        const rewriteToBucketRoot = new cloudfront.Function(this, 'AssetUploadRewriteFunction', {
-            code: cloudfront.FunctionCode.fromInline([
-                `var ALLOWED_ORIGINS = ${toFunctionLiteral(allowedOrigins)};`,
-                'function handler(event) {',
-                '  var request = event.request;',
-                "  if (request.method === 'OPTIONS') {",
-                '    var headers = {',
-                `      'access-control-allow-methods': { value: '${UPLOAD_ALLOWED_METHOD}' },`,
-                "      'access-control-allow-headers': { value: '*' },",
-                `      'access-control-max-age': { value: '${CORS_MAX_AGE_SECONDS}' }`,
-                '    };',
-                // Echo the caller's own Origin when the list is narrowed: a preflight
-                // may only be answered with `*` or the single requesting origin, so a
-                // multi-entry list cannot be returned verbatim. No match means no
-                // ACAO, and the browser's own check refuses the upload - which is the
-                // correct outcome, and a clearer one than a 403 here would be.
-                "    var origin = request.headers.origin ? request.headers.origin.value : '';",
-                "    if (ALLOWED_ORIGINS.length === 1 && ALLOWED_ORIGINS[0] === '*') {",
-                "      headers['access-control-allow-origin'] = { value: '*' };",
-                '    } else if (ALLOWED_ORIGINS.indexOf(origin) !== -1) {',
-                "      headers['access-control-allow-origin'] = { value: origin };",
-                '    }',
-                "    return { statusCode: 204, statusDescription: 'No Content', headers: headers };",
-                '  }',
-                "  request.uri = '/';",
-                '  delete request.headers.authorization;',
-                '  return request;',
-                '}',
-            ].join('\n')),
-        });
-        // `denyList('host')` emits CloudFormation's `allExcept`. In the HEADERS
-        // dimension only, that is the managed ALL_VIEWER_EXCEPT_HOST_HEADER policy
-        // - the shape this path was measured against. It is NOT that policy
-        // overall, and must not be replaced by it: the managed one is documented as
-        // "Cookies: All, Query strings: All", so adopting it would forward the
-        // editor session cookie to S3, which is one of the two hazards this whole
-        // policy exists to remove. Only the header behavior is shared.
-        //
-        // `Authorization` is handled by the function above, not here.
-        //
-        // Cookies go through `CookiesConfig`, not the header list (a CloudFront
-        // Function does not even see them in `request.headers`), so
-        // `cookieBehavior.none()` is what strips them: an upload route mounted on
-        // a site's own distribution would otherwise hand S3 - and S3's access logs
-        // - the editor session cookie. On the dedicated distribution recommended
-        // in `uploadBehavior()` a cross-origin XHR without `withCredentials` sends
-        // none in the first place; this makes it true either way.
-        const originRequestPolicy = new cloudfront.OriginRequestPolicy(this, 'AssetUploadOriginRequestPolicy', {
-            cookieBehavior: cloudfront.OriginRequestCookieBehavior.none(),
-            headerBehavior: cloudfront.OriginRequestHeaderBehavior.denyList('host'),
-            // A presigned POST carries everything in the multipart body.
-            queryStringBehavior: cloudfront.OriginRequestQueryStringBehavior.none(),
-        });
-        // The edge supplies Access-Control-Allow-Origin, scoped to this behavior
-        // only. This is the measurement that unblocked the whole design: a
-        // response-headers policy DOES attach ACAO to a 2xx from an unsigned S3
-        // origin on POST with NO bucket CORS configuration at all (204, `ACAO: *`,
-        // object landed). Acceptance and advertisement are independent in S3 -
-        // bucket CORS governs only whether S3 advertises - which is exactly the
-        // property that lets this construct avoid writing a bucket CORS rule.
-        //
-        // `originOverride: true` so the header is ours deterministically even on a
-        // bucket that does have its own CORS configuration.
-        //
-        // AllowMethods/AllowHeaders/MaxAge take effect only on a CORS PREFLIGHT,
-        // and this path DOES trigger one - see the CloudFront Function above, which
-        // answers it, and which exists because nothing else would. They are set
-        // here anyway, sharing `UPLOAD_ALLOWED_METHOD` with that function so the
-        // two cannot tell a browser different things, and because a response
-        // headers policy is documented to decorate responses without saying whether
-        // a function-generated one is among them. If it is, `originOverride: true`
-        // means the policy's values REPLACE the function's identical ones; if it is
-        // not, the function's stand alone. Either way the viewer sees exactly one
-        // of each, which is what makes it safe not to know.
-        const responseHeadersPolicy = new cloudfront.ResponseHeadersPolicy(this, 'AssetUploadResponseHeadersPolicy', {
-            corsBehavior: {
-                accessControlAllowOrigins: allowedOrigins,
-                accessControlAllowCredentials: false,
-                accessControlAllowMethods: [UPLOAD_ALLOWED_METHOD],
-                accessControlAllowHeaders: ['*'],
-                accessControlMaxAge: Duration.seconds(CORS_MAX_AGE_SECONDS),
-                originOverride: true,
-            },
-        });
-        return {
-            origin: uploadOrigin,
-            // A POST is 405 without this. CloudFront offers no narrower set that
-            // includes POST - GET_HEAD, GET_HEAD_OPTIONS and ALL are the only three.
-            // The URI rewrite above is what makes that acceptable.
-            allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
-            // HTTPS_ONLY, NOT the read behaviors' REDIRECT_TO_HTTPS. CloudFront
-            // redirects with 301, and a browser turns a 301'd POST into a GET - so
-            // an `http://` upload URL would silently become a bodyless GET that this
-            // behavior rewrites to `/` and S3 refuses, with the file never sent.
-            // HTTPS_ONLY answers 403 instead: same refusal, visible.
-            viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.HTTPS_ONLY,
-            // Nothing on this route is cacheable, and CACHING_DISABLED's all-`none`
-            // cache key is also what keeps the origin request policy above legal
-            // (CloudFront requires it to be a superset of the cache key).
-            cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
-            originRequestPolicy,
-            responseHeadersPolicy,
-            functionAssociations: [
-                {
-                    function: rewriteToBucketRoot,
-                    eventType: cloudfront.FunctionEventType.VIEWER_REQUEST,
-                },
-            ],
-        };
-    }
     /**
      * The two CloudFront behavior configs this system needs.
      *
-     * If you use this rather than `attachTo` -- which now takes an `overrides`
-     * parameter, so needing per-behavior options is no longer a reason to fall
-     * back here -- you own the ordering, and you should assert it: read the
+     * 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.
      *
@@ -788,6 +970,13 @@ export class AssetSupport extends Construct {
      * 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.
      */
     uploadBehavior() {
         if (!this.uploadOptions) {
@@ -798,7 +987,22 @@ export class AssetSupport extends Construct {
         }
         // Memoized: calling this twice must not attach two sets of policies, and
         // must not fail on duplicate construct ids.
-        this.upload ??= this.buildUploadBehavior(this.uploadOptions);
+        //
+        // `scope` is `this`, which is what keeps the three child ids
+        // (`AssetUploadRewriteFunction` and the two policies) exactly where they
+        // were before the builder moved out of this class - the emitted template
+        // is unchanged, so no existing deployment sees a resource replacement.
+        //
+        // `validateUploadBehaviorOptions` is NOT re-run here: the constructor
+        // already ran it on these same options, and `this.uploadOptions` is its
+        // own snapshot, so there is nothing a second pass could catch.
+        this.upload ??= buildUploadBehavior(this, { ...this.uploadOptions, bucket: this.bucket }, 'AssetSupport: uploadBehavior');
+        // The builder returns the origin it made; the attach guard needs a
+        // reference to it (see `UploadOrigin`), and this is the only place that
+        // knows the two belong to the same construct.
+        if (this.upload.origin instanceof UploadOrigin) {
+            this.uploadOrigin = this.upload.origin;
+        }
         return this.upload;
     }
     /**
@@ -838,14 +1042,11 @@ export class AssetSupport extends Construct {
      * has left this method's remit and should use `assetBehaviors()` - and keep
      * their own ordering assertion.
      *
-     * Typed `Partial<AddBehaviorOptions>` because that is exactly what
-     * `addBehavior(pattern, origin, behaviorOptions?)` accepts - `origin` is a
-     * POSITIONAL argument there, so `BehaviorOptions` (which is
-     * `AddBehaviorOptions` plus `origin`) would let a caller pass a key the call
-     * silently ignores. Measured, because the first version of this comment
-     * claimed the opposite: widening the parameter and passing an `origin`
-     * override changes nothing in the emitted template, so this narrowing
-     * prevents a confusing no-op rather than a broken origin group.
+     * 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
@@ -864,14 +1065,14 @@ export class AssetSupport extends Construct {
         // ['/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 (distributionsWithAssetBehaviors.has(distribution)) {
+        if (distribution.node.tryFindChild(ATTACHED_MARKER_ID)) {
             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.`);
         }
-        distributionsWithAssetBehaviors.add(distribution);
+        new Construct(distribution, ATTACHED_MARKER_ID);
         // Drop explicitly-`undefined` keys before merging. A spread copies own
         // enumerable keys INCLUDING ones whose value is undefined, so
         // `{ ...transformRest, ...{ cachePolicy: undefined } }` deletes the

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

@@ -69,12 +69,13 @@ export interface CanopyCmsDistributionProps {
      * order matters. Calls `assetSupport.attachTo(distribution)` for you right
      * after construction, with nothing to forget.
      *
-     * NOT fully equivalent to calling `attachTo` yourself: this path cannot pass
-     * that method's `overrides` argument. If the asset behaviors need
-     * per-behavior options - a viewer-request function for tier auth being the
-     * motivating case, since without it `/assets/*` is anonymously readable on
-     * an authenticated tier - drop this prop and call
-     * `assetSupport.attachTo(this.distribution, { ... })` after construction.
+     * If the asset behaviors need per-behavior options - a viewer-request
+     * function for tier auth being the motivating case, since without it
+     * `/assets/*` is anonymously readable on an authenticated tier - pass
+     * `assetBehaviorOverrides` alongside this prop. That requirement used to mean
+     * dropping this prop and hand-calling `attachTo` after construction, which
+     * sent exactly the adopter who most needs the ordering guarantee back to the
+     * manual path this prop exists to replace.
      *
      * Prefer this over passing `assetSupport.assetBehaviors()` through
      * `additionalBehaviors` by hand - that stays available as an escape hatch
@@ -89,6 +90,27 @@ export interface CanopyCmsDistributionProps {
      * @default - no asset behaviors are attached
      */
     assetSupport?: AssetSupport;
+    /**
+     * Per-behavior options merged into BOTH asset behaviors, forwarded verbatim
+     * to `AssetSupport.attachTo()`'s `overrides` parameter - see that method's
+     * doc comment for the merge semantics and for why the same set goes to both.
+     *
+     * The motivating case is a distribution running a viewer-request function on
+     * every behavior (tier basic-auth): without the same `functionAssociations`
+     * on the asset behaviors, `/assets/*` is anonymously readable on an
+     * authenticated tier.
+     *
+     * Useless without `assetSupport`, and silently so - there would be no
+     * behaviors to merge it into - so that combination throws from this
+     * construct's CONSTRUCTOR rather than being ignored. (A constructor throw,
+     * not an `addValidation`: nothing later can make the combination valid. An
+     * adopter sharing one props object across tiers, with `assetSupport` present
+     * on only some of them, should make the whole prop conditional rather than
+     * the overrides object.)
+     *
+     * @default - the asset behaviors are attached with no overrides
+     */
+    assetBehaviorOverrides?: Partial<cloudfront.AddBehaviorOptions>;
 }
 /**
  * Optional CDK construct for CanopyCMS CloudFront distribution.

package/dist/constructs/cms-distribution.js

@@ -152,6 +152,17 @@ function assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport) {
 export class CanopyCmsDistribution extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
+        // Overrides with nothing to override. They are merged into the asset
+        // behaviors and there are none, so the only outcome is that whatever the
+        // caller asked for - a tier-auth viewer function, most likely - silently
+        // does not happen.
+        if (props.assetBehaviorOverrides && !props.assetSupport) {
+            throw new Error('CanopyCmsDistribution: `assetBehaviorOverrides` was passed without `assetSupport`. ' +
+                'The overrides are merged into the asset behaviors, so with no AssetSupport to attach ' +
+                'there is nothing for them to apply to and they would be silently dropped - including ' +
+                'a viewer-request function for tier auth. Pass `assetSupport` as well, or drop the ' +
+                'overrides.');
+        }
         // ========================================================================
         // DNS — Hosted Zone lookup
         // ========================================================================
@@ -280,7 +291,11 @@ export class CanopyCmsDistribution extends Construct {
         // 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);
+        //
+        // `assetBehaviorOverrides` is forwarded so that needing per-behavior
+        // options is not a reason to leave this prop - and so the ordering
+        // guarantee survives the tier-auth case that most needs it.
+        props.assetSupport?.attachTo(this.distribution, props.assetBehaviorOverrides);
         // ========================================================================
         // DNS Records
         // ========================================================================

package/dist/constructs/cms-service.js

@@ -656,8 +656,12 @@ export class CanopyCmsService extends Construct {
             launchTemplate,
             minCapacity: 1,
             maxCapacity: 1,
-            healthCheck: autoscaling.HealthCheck.ec2({
-                grace: Duration.minutes(5),
+            // `healthChecks`, not the deprecated `healthCheck`/`HealthCheck.ec2({ grace })`:
+            // both synthesize the same HealthCheckType/HealthCheckGracePeriod, but the
+            // deprecated form prints a jsii warning on every synth -- in adopters'
+            // `cdk synth` output, not just ours -- and is slated for removal in v3.
+            healthChecks: autoscaling.HealthChecks.ec2({
+                gracePeriod: Duration.minutes(5),
             }),
             // Without an updatePolicy, CloudFormation's default behavior for an ASG
             // behind a changed launch template is to update the template resource

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { CanopyCmsService } from './constructs/cms-service.js';
 export type { CanopyCmsServiceProps } from './constructs/cms-service.js';
 export { CanopyCmsDistribution } from './constructs/cms-distribution.js';
 export type { CanopyCmsDistributionProps } from './constructs/cms-distribution.js';
-export { AssetSupport } from './constructs/asset-support.js';
-export type { AssetSupportProps, AssetCloudFrontBehaviors, AssetUploadBehaviorOptions, } from './constructs/asset-support.js';
+export { AssetSupport, assetUploadBehavior } from './constructs/asset-support.js';
+export type { AssetSupportProps, AssetCloudFrontBehaviors, AssetUploadBehaviorOptions, AssetUploadBehaviorRouteOptions, } from './constructs/asset-support.js';

package/dist/index.js

@@ -3,4 +3,4 @@ export { CmsWorker } from './worker.js';
 // CDK Constructs
 export { CanopyCmsService } from './constructs/cms-service.js';
 export { CanopyCmsDistribution } from './constructs/cms-distribution.js';
-export { AssetSupport } from './constructs/asset-support.js';
+export { AssetSupport, assetUploadBehavior } from './constructs/asset-support.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-cdk",
-  "version": "0.0.66-int.86",
+  "version": "0.0.67-int.88",
   "description": "AWS CDK constructs and EC2 worker for CanopyCMS deployment",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
   "peerDependencies": {
     "aws-cdk-lib": "^2.260.0",
     "constructs": "^10.0.0",
-    "canopycms": "0.0.66-int.86"
+    "canopycms": "0.0.67-int.88"
   },
   "peerDependenciesMeta": {
     "aws-cdk-lib": {
@@ -55,8 +55,8 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.66-int.86",
-    "canopycms-auth-clerk": "0.0.66-int.86"
+    "canopycms": "0.0.67-int.88",
+    "canopycms-auth-clerk": "0.0.67-int.88"
   },
   "scripts": {
     "build": "rm -rf dist && tsc && node ../../scripts/add-js-extensions.mjs dist",