canopycms-cdk 0.0.66 → 0.0.67-int.89

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

@@ -307,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).
@@ -361,16 +466,14 @@ export declare class AssetSupport extends Construct {
     /**
      * The origin inside `upload`, kept so the validation below can ask whether
      * that behavior was ever attached to a distribution - see `UploadOrigin`.
-     * Set by `buildUploadBehavior`, i.e. at the same moment as `upload`.
+     * 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 uploadOrigin?;
     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.
-     */
-    private buildUploadBehavior;
     /**
      * The two CloudFront behavior configs this system needs.
      *
@@ -430,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;
     /**

package/dist/constructs/asset-support.js

@@ -225,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).
@@ -385,8 +755,8 @@ export class AssetSupport extends Construct {
             code: lambda.Code.fromAsset(transformAssetDir),
             handler: 'handler.handler',
             // nodejs20.x was deprecated 2026-04-30; CDK's CloudFormation validation
-            // now fails synth on it. The esbuild bundle targets node20 and runs
-            // unchanged on the node22 runtime.
+            // now fails synth on it. The esbuild bundle (lambda/asset-transform/
+            // build.mjs) targets node22 to match; move the two together.
             runtime: lambda.Runtime.NODEJS_22_X,
             architecture: lambda.Architecture.ARM_64,
             memorySize: TRANSFORM_LAMBDA_MEMORY_MB,
@@ -432,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
@@ -509,7 +853,11 @@ export class AssetSupport extends Construct {
                             ', 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.",
+                            "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 [];
@@ -561,232 +909,6 @@ 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 UploadOrigin(this.bucket.bucketRegionalDomainName, {
-            protocolPolicy: cloudfront.OriginProtocolPolicy.HTTPS_ONLY,
-        });
-        this.uploadOrigin = uploadOrigin;
-        // 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(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.
      *
@@ -848,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) {
@@ -858,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;
     }
     /**

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",
+  "version": "0.0.67-int.89",
   "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"
+    "canopycms": "0.0.67-int.89"
   },
   "peerDependenciesMeta": {
     "aws-cdk-lib": {
@@ -55,12 +55,12 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.66",
-    "canopycms-auth-clerk": "0.0.66"
+    "canopycms-auth-clerk": "0.0.67-int.89",
+    "canopycms": "0.0.67-int.89"
   },
   "scripts": {
     "build": "rm -rf dist && tsc && node ../../scripts/add-js-extensions.mjs dist",
-    "build:worker": "esbuild worker/index.ts --bundle --platform=node --target=node20 --format=esm --outfile=worker/dist/index.js --banner:js=\"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\"",
+    "build:worker": "esbuild worker/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=worker/dist/index.js --banner:js=\"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\"",
     "build:lambda": "node lambda/asset-transform/build.mjs",
     "build:test-fixtures": "pnpm run build:worker && node lambda/asset-transform/build.mjs --skip-native",
     "lint": "eslint src/ 'lambda/**/*.ts' 'canary/**/*.ts' 'worker/**/*.ts' 'test-support/**/*.ts'",