canopycms-cdk 0.0.66-int.84 → 0.0.66-int.86

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

@@ -1,5 +1,38 @@
 import { Construct } from 'constructs';
 import { Duration, RemovalPolicy, aws_cloudfront as cloudfront, aws_iam as iam, aws_lambda as lambda, aws_logs as logs, aws_s3 as s3 } from 'aws-cdk-lib';
+/**
+ * Configuration for the presigned-upload CloudFront behavior. See
+ * `AssetSupportProps.uploadBehavior` to switch it on and
+ * `AssetSupport.uploadBehavior()` for the topology it belongs in.
+ */
+export interface AssetUploadBehaviorOptions {
+    /**
+     * Origins the edge advertises in `Access-Control-Allow-Origin`, scoped to
+     * this behavior alone.
+     *
+     * `['*']` by default, and a wildcard is defensible HERE in a way a
+     * bucket-wide CORS rule is not, because **the edge authorises nothing**:
+     * measured, a presigned POST with a corrupted signature sent through this
+     * exact path returns 403 and nothing lands. Authority is entirely the
+     * presigned policy, which pins the bucket, the exact key, the content type,
+     * a size range and a 15-minute expiry. So the wildcard widens who may READ
+     * the response, not who may write - and the response is an empty 204.
+     *
+     * Narrow it to your editor origin(s) if you would rather; nothing else here
+     * depends on the wildcard.
+     *
+     * ORIGINS ARE MATCHED EXACTLY, and `'*'` is honoured only as the sole entry.
+     * CloudFront's response headers policy would accept a leftmost-subdomain
+     * pattern (`https://*.preview.example.com`), but the CORS preflight is
+     * answered at the edge by a CloudFront Function that compares strings, so a
+     * pattern would pass the POST response's policy and fail every preflight.
+     * Rather than half-honour it, the constructor refuses any entry containing
+     * `*` unless the list is exactly `['*']`.
+     *
+     * @default ['*']
+     */
+    readonly allowedOrigins?: string[];
+}
 export interface AssetSupportProps {
     /**
      * Use an existing bucket (BYO mode - e.g. a site's existing content
@@ -18,8 +51,46 @@ export interface AssetSupportProps {
      * (the editor's own origin(s) - e.g. `http://localhost:3000` in dev, or
      * the deployed editor's domain). Only applied in standalone mode (see
      * `bucket`).
+     *
+     * This exists solely to write the bucket's CORS rule, which is only needed
+     * because the browser POSTs presigned uploads cross-origin. `uploadBehavior`
+     * is the OTHER way to satisfy that requirement: it supplies
+     * `Access-Control-Allow-Origin` from the edge instead, so no bucket rule is
+     * written and no exact origin has to be named anywhere.
+     *
+     * Optional since that edge route exists - it was required while the bucket
+     * rule was the only route. Standalone mode still refuses to synth with
+     * NEITHER, because the resulting failure is a genuinely misleading one (see
+     * the error's own text). An empty array counts as absent: CloudFormation
+     * rejects a CORS rule with no origins, so it can only ever have been a
+     * mistake.
+     *
+     * @default - no bucket CORS rule; standalone mode then requires `uploadBehavior`
      */
-    readonly editorOrigins: string[];
+    readonly editorOrigins?: string[];
+    /**
+     * Build a CloudFront behavior that accepts the editor's presigned-POST
+     * uploads - the infrastructure half of `media.uploadUrl` (see the README's
+     * "Routing uploads through your own CDN"). Retrieve the result with
+     * `uploadBehavior()`, which also documents the distribution it belongs on.
+     *
+     * OFF unless set, and deliberately so: this is the only thing in this
+     * construct that puts a write-capable, OAC-UNSIGNED origin in front of the
+     * bucket, and that must never appear in a template by accident. Pass
+     * `uploadBehavior: {}` to take the defaults.
+     *
+     * BYO-BUCKET 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.
+     *
+     * @default - no upload behavior is built
+     */
+    readonly uploadBehavior?: AssetUploadBehaviorOptions;
     /**
      * Advisory upload-size cap in bytes. Not enforced by this construct -
      * the actual cap comes from the presigned POST's `content-length-range`
@@ -96,6 +167,32 @@ export interface AssetSupportProps {
      * never affected.
      */
     readonly transformOutputRetention?: Duration;
+    /**
+     * Execution role for the transform Lambda (default: CDK creates one).
+     *
+     * Set this when the role's ARN has to be computable WITHOUT a reference to
+     * this construct - the case that motivated the prop is an asset bucket in a
+     * different AWS account from the compute, where the resource-policy half of
+     * the cross-account grant must be written in the bucket's own stack and needs
+     * the principal as a plain string. Reading `transformFunction.role` across an
+     * account boundary does not give you that: CDK emits `Fn::GetStackOutput`, a
+     * CDK-CLI-only intrinsic resolved at deploy time, so the coupling is
+     * invisible to CloudFormation and unusable by any deploy path that is not
+     * `cdk deploy`. Create a deterministically NAMED role instead and both stacks
+     * can compute `arn:aws:iam::<account>:role/<name>` from literals, with
+     * nothing crossing between them.
+     *
+     * A named IAM role means the consuming stack needs `CAPABILITY_NAMED_IAM`,
+     * and cannot be replaced in place without a rename - that trade is yours to
+     * make here, which is the point of taking a role rather than a name.
+     *
+     * `iam.Role`, not `iam.IRole`, ON PURPOSE - an imported role silently
+     * discards the managed policies this construct has to re-attach. See
+     * `attachLambdaExecutionPolicies` (./lambda-execution-role) for what CDK
+     * drops when a role is passed, and why the narrower type is what makes the
+     * compensation reliable.
+     */
+    readonly transformRole?: iam.Role;
     /**
      * Name for the transform Lambda's CloudWatch log group (default:
      * `/canopycms/<stackName>/transform`). Deliberately NOT
@@ -127,6 +224,16 @@ export declare const ASSETS_TRANSFORM_PATH_PATTERN: string;
  * `attachTo()` (below) or `CanopyCmsDistribution`'s `assetSupport` prop
  * instead. Exported so `cms-distribution.ts`'s synth-time guard can
  * recognize the mistake and name it in its error.
+ *
+ * `uploadBehavior()` deliberately adds NO key here, considered and rejected
+ * when it was added. It returns a bare `BehaviorOptions` rather than a named
+ * property of a returned object, so there is no spread to get wrong in the
+ * first place - and a speculative `'upload'` entry would actively misfire on
+ * an adopter whose distribution has a real upload route, since CloudFront
+ * treats a path pattern's leading slash as optional and `upload` is a legal
+ * spelling of `/upload` (see `normalizePathPattern` in cms-distribution.ts).
+ * Keep this list to property names that actually exist on
+ * `AssetCloudFrontBehaviors`.
  */
 export declare const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS: readonly ["assets", "assetsTransform"];
 /**
@@ -202,6 +309,9 @@ export interface AssetCloudFrontBehaviors {
  *   for why the order is the whole point); `assetBehaviors()` is the escape
  *   hatch for a distribution built entirely by hand (see
  *   `AssetCloudFrontBehaviors`'s doc comment).
+ * - `uploadBehavior()`, opt-in, the write half: a CloudFront behavior that
+ *   accepts the editor's presigned-POST uploads, for adopters who set
+ *   `media.uploadUrl`. Belongs on its own distribution - see that method.
  * - `grantUploadAccess()`, the exact prefix-scoped grants the CMS/editor
  *   principal needs to run `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts).
  */
@@ -217,8 +327,29 @@ export declare class AssetSupport extends Construct {
     /** Effective advisory upload-size cap (see `AssetSupportProps.maxUploadBytes`). */
     readonly maxUploadBytes: number;
     private readonly behaviors;
+    /** Set only when `AssetSupportProps.uploadBehavior` is set; validated in the constructor. */
+    private readonly uploadOptions?;
+    /**
+     * Memoized on the first `uploadBehavior()` call, NOT built in the
+     * constructor. Opting in creates three CloudFront resources (function,
+     * origin request policy, response headers policy) and response headers
+     * policies have a default account quota of 20 - so an adopter who sets the
+     * prop on a per-environment `AssetSupport` while building the single shared
+     * upload distribution the accessor recommends would otherwise mint a set per
+     * environment for one route. Deferring is invisible other than in what gets
+     * emitted, with one exception worth knowing rather than discovering: calling
+     * the accessor AFTER a synth has run modifies the construct tree, and CDK
+     * refuses that with `ConstructTreeModifiedAfterSynth` naming the constructs
+     * added. Loud, not silent.
+     */
+    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.
+     */
+    private buildUploadBehavior;
     /**
      * The two CloudFront behavior configs this system needs.
      *
@@ -235,6 +366,51 @@ export declare class AssetSupport extends Construct {
      * doc comment for that shape and its ordering requirements.
      */
     assetBehaviors(): AssetCloudFrontBehaviors;
+    /**
+     * The CloudFront behavior that accepts the editor's presigned-POST uploads -
+     * the infrastructure half of `media.uploadUrl`. Requires
+     * `AssetSupportProps.uploadBehavior`.
+     *
+     * GIVE IT ITS OWN DISTRIBUTION, serving this route and nothing else:
+     *
+     * ```ts
+     * const uploads = new cloudfront.Distribution(this, 'AssetUploads', {
+     *   defaultBehavior: assetSupport.uploadBehavior(),
+     * })
+     * // media.uploadUrl = `https://${uploads.distributionDomainName}/`
+     * ```
+     *
+     * No custom domain or certificate is needed - the `d111...cloudfront.net`
+     * name is a perfectly good `uploadUrl` - and as the default behavior of a
+     * one-route distribution there is no path pattern and so no ordering
+     * question of the kind `attachTo()` exists to settle.
+     *
+     * Two shapes this deliberately is NOT, both settled 2026-09-11 (the record
+     * is `.claude/future-tasks/resolved/asset-support-upload-behavior.md`):
+     *
+     * - NOT a behavior on the site's own distribution. `CustomErrorResponses`
+     *   are distribution-wide, so a site that maps 403 to its own 404 page
+     *   applies that to S3's upload errors too and the editor reports the
+     *   substituted status. The site's cookies and any cached basic-auth
+     *   credential are also live hazards there that have to be stripped by
+     *   policy and function (`buildUploadBehavior` removes both - cookies via
+     *   the origin request policy, `Authorization` in the viewer-request
+     *   function) rather than simply never
+     *   being sent. It works; it is just strictly worse.
+     * - NOT one shared distribution serving asset reads AND writes for every
+     *   environment. One assets distribution means one `AssetSupport`, and
+     *   `AssetSupport` owns the transform Lambda - so it would also mean one
+     *   transform Lambda shared by every environment, and that Lambda ships
+     *   inside this package. A `canopycms-cdk` bump would then move every
+     *   environment's asset pipeline at once, which is a graduated rollout
+     *   traded away for an upload path. Reads and transforms stay
+     *   per-environment; only the upload route moves.
+     *
+     * The upload route is the one part of this system with no per-environment
+     * code in it - it depends on the bucket and nothing else - which is why it
+     * is the part that can be split off this way.
+     */
+    uploadBehavior(): cloudfront.BehaviorOptions;
     /**
      * Attach both asset behaviors to a concrete CloudFront distribution, in the
      * only safe order.

package/dist/constructs/asset-support.js

@@ -2,7 +2,8 @@ import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Construct } from 'constructs';
-import { Duration, RemovalPolicy, Stack, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_lambda as lambda, aws_logs as logs, aws_s3 as s3, } from 'aws-cdk-lib';
+import { Duration, RemovalPolicy, Stack, Token, aws_cloudfront as cloudfront, aws_cloudfront_origins as origins, aws_lambda as lambda, aws_logs as logs, aws_s3 as s3, } from 'aws-cdk-lib';
+import { attachLambdaExecutionPolicies } from './lambda-execution-role.js';
 // This package (`canopycms-cdk`) is `"type": "module"`, so its compiled
 // output is real ESM - `__dirname` is not a global there. Derive it from
 // `import.meta.url` instead (mirrors ../../lambda/asset-transform/build.mjs).
@@ -50,8 +51,36 @@ const PREFIXES = {
     public: 'assets',
     transform: 'assets/t',
 };
-/** S3 CORS preflight cache duration for presigned-POST uploads from the editor. */
+/**
+ * CORS preflight cache duration for presigned-POST uploads from the editor.
+ * Used for the bucket's own CORS rule and, when `uploadBehavior` is on, for
+ * both the edge's preflight response and its response headers policy.
+ */
 const CORS_MAX_AGE_SECONDS = 3000;
+/**
+ * The only method the upload route exists to serve. Shared by the preflight
+ * response the CloudFront Function returns and the response headers policy's
+ * `Access-Control-Allow-Methods`, so a browser cannot be told two different
+ * things about what it may send. (The BEHAVIOR still allows all methods -
+ * CloudFront has no narrower set containing POST - which is a separate concern
+ * handled by the URI rewrite; see `buildUploadBehavior`.)
+ */
+const UPLOAD_ALLOWED_METHOD = 'POST';
+/**
+ * Render a string array as a JavaScript literal for embedding in CloudFront
+ * Function source.
+ *
+ * `JSON.stringify` already escapes quotes and backslashes, so an adopter's
+ * origin string cannot terminate the literal and inject code. It does NOT
+ * escape U+2028/U+2029, which are legal in JSON but were line terminators in
+ * JavaScript before ES2019 - and the CloudFront Functions runtime is not a
+ * runtime to find out about on. Escaping them costs one `replace`.
+ */
+function toFunctionLiteral(values) {
+    return JSON.stringify(values)
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
 /** Matches packages/canopycms/src/assets/store-s3.ts's `DEFAULT_MAX_UPLOAD_BYTES`. */
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const TRANSFORM_LAMBDA_MEMORY_MB = 1536;
@@ -149,6 +178,16 @@ export const ASSETS_TRANSFORM_PATH_PATTERN = `/${PREFIXES.transform}/*`;
  * `attachTo()` (below) or `CanopyCmsDistribution`'s `assetSupport` prop
  * instead. Exported so `cms-distribution.ts`'s synth-time guard can
  * recognize the mistake and name it in its error.
+ *
+ * `uploadBehavior()` deliberately adds NO key here, considered and rejected
+ * when it was added. It returns a bare `BehaviorOptions` rather than a named
+ * property of a returned object, so there is no spread to get wrong in the
+ * first place - and a speculative `'upload'` entry would actively misfire on
+ * an adopter whose distribution has a real upload route, since CloudFront
+ * treats a path pattern's leading slash as optional and `upload` is a legal
+ * spelling of `/upload` (see `normalizePathPattern` in cms-distribution.ts).
+ * Keep this list to property names that actually exist on
+ * `AssetCloudFrontBehaviors`.
  */
 export const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS = ['assets', 'assetsTransform'];
 /**
@@ -168,6 +207,9 @@ export const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS = ['assets', 'assetsTransform'];
  *   for why the order is the whole point); `assetBehaviors()` is the escape
  *   hatch for a distribution built entirely by hand (see
  *   `AssetCloudFrontBehaviors`'s doc comment).
+ * - `uploadBehavior()`, opt-in, the write half: a CloudFront behavior that
+ *   accepts the editor's presigned-POST uploads, for adopters who set
+ *   `media.uploadUrl`. Belongs on its own distribution - see that method.
  * - `grantUploadAccess()`, the exact prefix-scoped grants the CMS/editor
  *   principal needs to run `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts).
  */
@@ -194,6 +236,32 @@ export class AssetSupport extends Construct {
                 '  pnpm --filter canopycms-cdk run build:lambda');
         }
         this.maxUploadBytes = props.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+        // An empty array is treated as absent throughout: CloudFormation rejects a
+        // CORS rule whose AllowedOrigins is empty, so `editorOrigins: []` could
+        // only ever have been a mistake, and it is better caught by the check
+        // below than by a deploy-time template rejection.
+        const editorOrigins = props.editorOrigins ?? [];
+        // A browser presigned upload needs an Access-Control-Allow-Origin from
+        // SOMEWHERE - the bucket's own CORS rule (`editorOrigins`) or the edge
+        // (`uploadBehavior`). Standalone mode owns the bucket, so it can tell that
+        // neither is configured and say so here rather than let it be discovered
+        // in a browser. BYO-bucket mode cannot: the caller owns that bucket's CORS
+        // configuration and this construct has no way to read it (`IBucket` has no
+        // `addCorsRule`, which is the same reason `editorOrigins` is inert there).
+        if (!props.bucket && editorOrigins.length === 0 && !props.uploadBehavior) {
+            throw new Error('AssetSupport: standalone mode creates the bucket, and a browser presigned upload needs ' +
+                'Access-Control-Allow-Origin from either the bucket or the edge - this construct was ' +
+                'given neither. Pass `editorOrigins` (the editor origin(s) that POST uploads), or ' +
+                '`uploadBehavior` to route uploads through a CloudFront distribution that supplies the ' +
+                'header at the edge. If you have wired an equivalent upload path yourself, outside ' +
+                'this construct, pass `editorOrigins` anyway - a bucket CORS rule your own path makes ' +
+                'redundant is harmless, and this check cannot see that path.\n' +
+                'Worth knowing why this is worth failing on: S3 ACCEPTS a cross-origin presigned POST ' +
+                'with no CORS rule at all and simply declines to ADVERTISE it (measured: 204, no ' +
+                'ACAO header, object landed). So the object reaches asset-staging/ and the browser ' +
+                'still reports the upload as a network error - a failure that looks like anything ' +
+                'except missing CORS.');
+        }
         if (props.bucket) {
             this.bucket = props.bucket;
         }
@@ -229,15 +297,20 @@ export class AssetSupport extends Construct {
                         expiration: props.transformOutputRetention ?? TRANSFORM_OUTPUT_RETENTION,
                     },
                 ],
-                cors: [
-                    {
-                        id: 'editor-presigned-upload',
-                        allowedOrigins: props.editorOrigins,
-                        allowedMethods: [s3.HttpMethods.POST, s3.HttpMethods.PUT, s3.HttpMethods.GET],
-                        allowedHeaders: ['*'],
-                        maxAge: CORS_MAX_AGE_SECONDS,
-                    },
-                ],
+                // Omitted entirely when `editorOrigins` is absent - the upload is then
+                // going through `uploadBehavior`, which supplies ACAO at the edge, and
+                // writing a rule with no origins would be an invalid template anyway.
+                cors: editorOrigins.length > 0
+                    ? [
+                        {
+                            id: 'editor-presigned-upload',
+                            allowedOrigins: editorOrigins,
+                            allowedMethods: [s3.HttpMethods.POST, s3.HttpMethods.PUT, s3.HttpMethods.GET],
+                            allowedHeaders: ['*'],
+                            maxAge: CORS_MAX_AGE_SECONDS,
+                        },
+                    ]
+                    : undefined,
             });
         }
         // Dedicated CloudWatch log group for the transform Lambda's stdout/
@@ -257,7 +330,18 @@ export class AssetSupport extends Construct {
             retention: props.transformLogRetention ?? logs.RetentionDays.THREE_MONTHS,
             removalPolicy: RemovalPolicy.DESTROY,
         });
+        // Re-attach what CDK silently drops for a caller-supplied role. MUST run
+        // for every passed role - see that function's doc comment. This function
+        // is not VPC-attached, so it takes basic execution only; the test suite
+        // pins the absence of the VPC-ENI policy here specifically, so that this
+        // call site and the CMS Lambda's cannot be collapsed into one.
+        if (props.transformRole) {
+            attachLambdaExecutionPolicies(props.transformRole, { vpc: false });
+        }
         this.transformFunction = new lambda.Function(this, 'TransformFunction', {
+            // Default (unset) leaves CDK to create the execution role, with its own
+            // managed policies intact. See `transformRole`'s doc comment.
+            role: props.transformRole,
             // Built by `pnpm run build:lambda` (lambda/asset-transform/build.mjs) -
             // esbuild bundle + a real linux/arm64 `npm install sharp` alongside it,
             // no Docker. `cdk synth`/`deploy` need that script run first; it is
@@ -313,6 +397,75 @@ 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.`);
+        }
+        // Snapshotted, not aliased. The guard above runs now but `allowedOrigins`
+        // is not READ until the accessor builds the behavior, so holding the
+        // caller's array by reference would let `origins.length = 0` in between
+        // walk straight past the check just made.
+        this.uploadOptions = props.uploadBehavior && {
+            ...props.uploadBehavior,
+            allowedOrigins: props.uploadBehavior.allowedOrigins?.slice(),
+        };
+        // Setting `uploadBehavior` SATISFIES the standalone guard above, but only
+        // calling `uploadBehavior()` and attaching the result 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.
+        //
+        // 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) {
+                    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.',
+                    ];
+                }
+                return [];
+            },
+        });
     }
     buildBehaviors() {
         const s3Origin = origins.S3BucketOrigin.withOriginAccessControl(this.bucket);
@@ -359,6 +512,221 @@ 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.
      *
@@ -377,6 +745,62 @@ export class AssetSupport extends Construct {
     assetBehaviors() {
         return this.behaviors;
     }
+    /**
+     * The CloudFront behavior that accepts the editor's presigned-POST uploads -
+     * the infrastructure half of `media.uploadUrl`. Requires
+     * `AssetSupportProps.uploadBehavior`.
+     *
+     * GIVE IT ITS OWN DISTRIBUTION, serving this route and nothing else:
+     *
+     * ```ts
+     * const uploads = new cloudfront.Distribution(this, 'AssetUploads', {
+     *   defaultBehavior: assetSupport.uploadBehavior(),
+     * })
+     * // media.uploadUrl = `https://${uploads.distributionDomainName}/`
+     * ```
+     *
+     * No custom domain or certificate is needed - the `d111...cloudfront.net`
+     * name is a perfectly good `uploadUrl` - and as the default behavior of a
+     * one-route distribution there is no path pattern and so no ordering
+     * question of the kind `attachTo()` exists to settle.
+     *
+     * Two shapes this deliberately is NOT, both settled 2026-09-11 (the record
+     * is `.claude/future-tasks/resolved/asset-support-upload-behavior.md`):
+     *
+     * - NOT a behavior on the site's own distribution. `CustomErrorResponses`
+     *   are distribution-wide, so a site that maps 403 to its own 404 page
+     *   applies that to S3's upload errors too and the editor reports the
+     *   substituted status. The site's cookies and any cached basic-auth
+     *   credential are also live hazards there that have to be stripped by
+     *   policy and function (`buildUploadBehavior` removes both - cookies via
+     *   the origin request policy, `Authorization` in the viewer-request
+     *   function) rather than simply never
+     *   being sent. It works; it is just strictly worse.
+     * - NOT one shared distribution serving asset reads AND writes for every
+     *   environment. One assets distribution means one `AssetSupport`, and
+     *   `AssetSupport` owns the transform Lambda - so it would also mean one
+     *   transform Lambda shared by every environment, and that Lambda ships
+     *   inside this package. A `canopycms-cdk` bump would then move every
+     *   environment's asset pipeline at once, which is a graduated rollout
+     *   traded away for an upload path. Reads and transforms stay
+     *   per-environment; only the upload route moves.
+     *
+     * The upload route is the one part of this system with no per-environment
+     * code in it - it depends on the bucket and nothing else - which is why it
+     * is the part that can be split off this way.
+     */
+    uploadBehavior() {
+        if (!this.uploadOptions) {
+            throw new Error('AssetSupport: uploadBehavior() needs the `uploadBehavior` prop, which is off by ' +
+                'default because it is the only thing this construct builds that puts a ' +
+                'write-capable, OAC-UNSIGNED origin in front of the bucket. Pass ' +
+                '`uploadBehavior: {}` to opt in and take the defaults.');
+        }
+        // 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);
+        return this.upload;
+    }
     /**
      * Attach both asset behaviors to a concrete CloudFront distribution, in the
      * only safe order.

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

@@ -1,5 +1,5 @@
 import { Construct } from 'constructs';
-import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
+import { Duration, RemovalPolicy, aws_ec2 as ec2, aws_efs as efs, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_logs as logs } from 'aws-cdk-lib';
 import type { IBucket } from 'aws-cdk-lib/aws-s3';
 /**
  * Default CMS Lambda timeout.
@@ -168,6 +168,38 @@ export interface CanopyCmsServiceProps {
      * default name would collide).
      */
     workerLogGroupName?: string;
+    /**
+     * Execution role for the CMS Lambda (default: CDK creates one).
+     *
+     * Set this when the role's ARN has to be computable WITHOUT a reference to
+     * this construct - the motivating case is an asset bucket in a different AWS
+     * account from the compute, where the resource-policy half of the
+     * cross-account grant must be written in the bucket's own stack and needs the
+     * principal as a plain string. Reading `lambdaFunction.role` across an
+     * account boundary does not give you that: CDK emits `Fn::GetStackOutput`, a
+     * CDK-CLI-only intrinsic resolved at deploy time, so the coupling is
+     * invisible to CloudFormation and unusable by any deploy path that is not
+     * `cdk deploy`. Create a deterministically NAMED role instead and both stacks
+     * can compute `arn:aws:iam::<account>:role/<name>` from literals, with
+     * nothing crossing between them.
+     *
+     * A named IAM role means the consuming stack needs `CAPABILITY_NAMED_IAM`,
+     * and cannot be replaced in place without a rename - that trade is yours to
+     * make here, which is the point of taking a role rather than a name.
+     *
+     * This Lambda is VPC-attached, which makes the compensation in
+     * `attachLambdaExecutionPolicies` (./lambda-execution-role) load-bearing
+     * rather than cosmetic: CDK discards `AWSLambdaVPCAccessExecutionRole` for a
+     * passed role, and without it the function cannot create ENIs and so cannot
+     * start - after synthesizing and deploying clean. The construct re-attaches
+     * it, which is also why this is `iam.Role` and not `iam.IRole` (an imported
+     * role would drop it again, silently). Everything else survives a passed role
+     * untouched: the EFS access-point statements, the `cmsLogGroup` write grant
+     * and the `assetBucket` grants all land on it.
+     *
+     * The EC2 worker has its own instance role and is unaffected by this prop.
+     */
+    lambdaRole?: iam.Role;
     /**
      * Retention for the CMS Lambda's CloudWatch log group (default: three
      * months / 90 days).

package/dist/constructs/cms-service.js

@@ -2,6 +2,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Construct } from 'constructs';
 import { Duration, RemovalPolicy, Stack, aws_ec2 as ec2, aws_efs as efs, aws_iam as iam, aws_lambda as lambda, aws_autoscaling as autoscaling, aws_s3_assets as s3assets, aws_logs as logs, } from 'aws-cdk-lib';
+import { attachLambdaExecutionPolicies } from './lambda-execution-role.js';
 // This package (`canopycms-cdk`) is `"type": "module"`, so its compiled
 // output is real ESM - `__dirname` is not a global there. Found while
 // fixing this construct's B1 deploy blocker below: the worker asset path a
@@ -404,8 +405,19 @@ export class CanopyCmsService extends Construct {
             removalPolicy: RemovalPolicy.DESTROY,
         });
         this.timeout = props.timeout ?? DEFAULT_CMS_LAMBDA_TIMEOUT;
+        // Re-attach what CDK silently drops for a caller-supplied role. MUST run
+        // for every passed role, and `vpc: true` here is the load-bearing part:
+        // this function is VPC-attached, so a role without
+        // AWSLambdaVPCAccessExecutionRole cannot create ENIs and the Lambda cannot
+        // start, having deployed clean. See that function's doc comment.
+        if (props.lambdaRole) {
+            attachLambdaExecutionPolicies(props.lambdaRole, { vpc: true });
+        }
         this.lambdaFunction = new lambda.DockerImageFunction(this, 'CmsFunction', {
             code: props.cmsDockerImage,
+            // Default (unset) leaves CDK to create the execution role, with its own
+            // managed policies intact. See `lambdaRole`'s doc comment.
+            role: props.lambdaRole,
             memorySize: props.memorySize ?? 2048,
             timeout: this.timeout,
             reservedConcurrentExecutions: props.reservedConcurrency ?? 10,

package/dist/constructs/lambda-execution-role.d.ts

@@ -0,0 +1,60 @@
+import { aws_iam as iam } from 'aws-cdk-lib';
+export interface LambdaExecutionPolicyOptions {
+    /**
+     * Whether the function this role belongs to is VPC-attached (i.e. was given
+     * a `vpc` prop). Mirrors the `props.vpc &&` condition in the CDK snippet
+     * above rather than being decided here, so the two cannot drift.
+     *
+     * Required rather than defaulted: getting it wrong on a VPC function
+     * produces a Lambda that cannot start, and a default would let a new call
+     * site inherit the wrong answer by saying nothing.
+     */
+    readonly vpc: boolean;
+}
+/**
+ * Re-attach what CDK drops when a `lambda.Function` is handed a pre-built
+ * execution role. Call this for every caller-supplied role, alongside passing
+ * that role to the function.
+ *
+ * The contract this maintains is deliberately the strong one: **passing a role
+ * yields the same effective permissions as letting the construct create one.**
+ * The weaker alternative - attach only what each function demonstrably still
+ * needs - is a judgment call that goes stale silently. Concretely, neither
+ * Lambda in this package strictly needs `AWSLambdaBasicExecutionRole` today:
+ * both log to a custom-named group (`/canopycms/<stackName>/...`), that
+ * policy's `logs:CreateLogStream`/`logs:PutLogEvents` are scoped to
+ * `arn:aws:logs:*:*:log-group:/aws/lambda/*:*` and so grant nothing for such a
+ * group, and an explicit `logGroup.grantWrite()` is what actually enables
+ * their logging. Attaching it regardless costs one managed-policy ARN and
+ * means the first change to either function's logging cannot quietly leave
+ * passed-role deployments behind.
+ *
+ * WHY THE PARAMETER IS THE CONCRETE `iam.Role` AND NOT `iam.IRole`, which is
+ * the type a CDK prop would normally take: `addManagedPolicy` does nothing
+ * useful on an imported role, in two distinct ways, neither of which surfaces
+ * an error.
+ *
+ * - `ImmutableRole.addManagedPolicy(_policy) {}` - an empty method body. This
+ *   is what `Role.fromRoleArn` returns for a CROSS-ACCOUNT role, or for any
+ *   role imported with `mutable: false`.
+ * - `ImportedRole.addManagedPolicy` (the same-account, still-mutable case)
+ *   attaches the policy only if it exposes `attachToRole`, which
+ *   `ManagedPolicy.fromAwsManagedPolicyName` does not - so it takes the
+ *   warning branch and emits nothing.
+ *
+ * Both confirmed on a synthesized template: no `AWS::IAM::Role` and no
+ * `AWS::IAM::Policy` resource appears in either case. So typed `IRole`, this
+ * function would silently no-op for every imported role and ship exactly the
+ * cannot-start Lambda it exists to prevent. There is no runtime guard
+ * available either - `ImmutableRole.addToPrincipalPolicy` returns
+ * `statementAdded: true` while emitting nothing, so the one signal CDK offers
+ * lies. Narrowing the type moves the failure to COMPILE time instead, which is
+ * the earliest it can be caught; `attachTo(distribution:
+ * cloudfront.Distribution)` in asset-support.ts narrows to a concrete class for
+ * the same kind of reason.
+ *
+ * Residual, documented rather than guarded because of its rarity: a role
+ * produced under `Role.customizeRoles` carries a precreated `ImportedRole` that
+ * `addManagedPolicy` delegates to, landing on the warning branch above.
+ */
+export declare function attachLambdaExecutionPolicies(role: iam.Role, options: LambdaExecutionPolicyOptions): void;

package/dist/constructs/lambda-execution-role.js

@@ -0,0 +1,90 @@
+import { aws_iam as iam } from 'aws-cdk-lib';
+/**
+ * The two AWS managed policies CDK's `lambda.Function` attaches to an
+ * execution role IT creates, and silently DISCARDS when one is passed in.
+ *
+ * Verbatim from `aws-cdk-lib/aws-lambda/lib/function.js` (checked against
+ * 2.265.0 here, and independently against 2.267.0 by the adopter who filed
+ * this):
+ *
+ * ```js
+ * managedPolicies.push(ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'))
+ * props.vpc && managedPolicies.push(ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'))
+ * this.role = props.role || new iam.Role(this, 'ServiceRole', { assumedBy: ..., managedPolicies })
+ * ```
+ *
+ * The array is built unconditionally and then reaches ONLY the `||` fallback.
+ * Pass a role and both entries are dropped with nothing logged. Confirmed on a
+ * synthesized template, not inferred: a VPC-attached function given a bare role
+ * emits an `AWS::IAM::Role` whose `ManagedPolicyArns` is absent entirely.
+ *
+ * For the VPC-attached CMS Lambda that is not a degradation, it is fatal and
+ * invisible: without `AWSLambdaVPCAccessExecutionRole` the function cannot
+ * create ENIs, so it cannot start at all - while synthesizing and deploying
+ * perfectly clean and failing only at invoke, a long way from the cause. Which
+ * is why every `role` prop in this package routes through here.
+ *
+ * NOT affected by passing a role, so deliberately not re-applied below (all
+ * three verified in the same CDK source):
+ *
+ * - EFS access-point statements - `config.policies.forEach(p => this.role?.addToPrincipalPolicy(p))`.
+ * - `initialPolicy` - `this.role.addToPrincipalPolicy(statement)` per statement.
+ * - Every `grant*` call, because `this.grantPrincipal = this.role`. That covers
+ *   `cmsLogGroup`/`transformLogGroup`'s `grantWrite` and all asset-bucket
+ *   grants, which land on the passed role exactly as they would on a created
+ *   one.
+ */
+const BASIC_EXECUTION_POLICY = 'service-role/AWSLambdaBasicExecutionRole';
+const VPC_ACCESS_POLICY = 'service-role/AWSLambdaVPCAccessExecutionRole';
+/**
+ * Re-attach what CDK drops when a `lambda.Function` is handed a pre-built
+ * execution role. Call this for every caller-supplied role, alongside passing
+ * that role to the function.
+ *
+ * The contract this maintains is deliberately the strong one: **passing a role
+ * yields the same effective permissions as letting the construct create one.**
+ * The weaker alternative - attach only what each function demonstrably still
+ * needs - is a judgment call that goes stale silently. Concretely, neither
+ * Lambda in this package strictly needs `AWSLambdaBasicExecutionRole` today:
+ * both log to a custom-named group (`/canopycms/<stackName>/...`), that
+ * policy's `logs:CreateLogStream`/`logs:PutLogEvents` are scoped to
+ * `arn:aws:logs:*:*:log-group:/aws/lambda/*:*` and so grant nothing for such a
+ * group, and an explicit `logGroup.grantWrite()` is what actually enables
+ * their logging. Attaching it regardless costs one managed-policy ARN and
+ * means the first change to either function's logging cannot quietly leave
+ * passed-role deployments behind.
+ *
+ * WHY THE PARAMETER IS THE CONCRETE `iam.Role` AND NOT `iam.IRole`, which is
+ * the type a CDK prop would normally take: `addManagedPolicy` does nothing
+ * useful on an imported role, in two distinct ways, neither of which surfaces
+ * an error.
+ *
+ * - `ImmutableRole.addManagedPolicy(_policy) {}` - an empty method body. This
+ *   is what `Role.fromRoleArn` returns for a CROSS-ACCOUNT role, or for any
+ *   role imported with `mutable: false`.
+ * - `ImportedRole.addManagedPolicy` (the same-account, still-mutable case)
+ *   attaches the policy only if it exposes `attachToRole`, which
+ *   `ManagedPolicy.fromAwsManagedPolicyName` does not - so it takes the
+ *   warning branch and emits nothing.
+ *
+ * Both confirmed on a synthesized template: no `AWS::IAM::Role` and no
+ * `AWS::IAM::Policy` resource appears in either case. So typed `IRole`, this
+ * function would silently no-op for every imported role and ship exactly the
+ * cannot-start Lambda it exists to prevent. There is no runtime guard
+ * available either - `ImmutableRole.addToPrincipalPolicy` returns
+ * `statementAdded: true` while emitting nothing, so the one signal CDK offers
+ * lies. Narrowing the type moves the failure to COMPILE time instead, which is
+ * the earliest it can be caught; `attachTo(distribution:
+ * cloudfront.Distribution)` in asset-support.ts narrows to a concrete class for
+ * the same kind of reason.
+ *
+ * Residual, documented rather than guarded because of its rarity: a role
+ * produced under `Role.customizeRoles` carries a precreated `ImportedRole` that
+ * `addManagedPolicy` delegates to, landing on the warning branch above.
+ */
+export function attachLambdaExecutionPolicies(role, options) {
+    role.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName(BASIC_EXECUTION_POLICY));
+    if (options.vpc) {
+        role.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName(VPC_ACCESS_POLICY));
+    }
+}

package/dist/index.d.ts

@@ -5,4 +5,4 @@ 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 } from './constructs/asset-support.js';
+export type { AssetSupportProps, AssetCloudFrontBehaviors, AssetUploadBehaviorOptions, } from './constructs/asset-support.js';

package/lambda/asset-transform/dist/handler.js

@@ -4368,6 +4368,66 @@ var init_collection = __esm({
   }
 });
 
+// ../canopycms/src/utils/sanitize-href.ts
+function declaresScheme(url) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
+}
+function isImplicitlyOffOrigin(url) {
+  if (declaresScheme(url)) return false;
+  try {
+    return new URL(url, SENTINEL_BASE).origin !== SENTINEL_BASE;
+  } catch {
+    return false;
+  }
+}
+function isHttpUrlOrSameOriginPath(value, opts = {}) {
+  if (value === "") return false;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 32 || code === 127) return false;
+  }
+  if (value.includes("?") || value.includes("#")) return false;
+  if (value.includes("\\")) return false;
+  if (DOT_SEGMENT.test(value)) return false;
+  if (declaresScheme(value)) {
+    if (!/^https?:\/\//i.test(value)) return false;
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  if (isImplicitlyOffOrigin(value)) {
+    return opts.allowProtocolRelative === true && value.startsWith("//") && value[2] !== "/";
+  }
+  return value.startsWith("/") && value[1] !== "/";
+}
+var SENTINEL_BASE, DOT_SEGMENT;
+var init_sanitize_href = __esm({
+  "../canopycms/src/utils/sanitize-href.ts"() {
+    "use strict";
+    SENTINEL_BASE = "https://relative.invalid";
+    DOT_SEGMENT = /(^|\/)(\.|%2e){1,2}(\/|$)/i;
+  }
+});
+
+// ../canopycms/src/config/schemas/url.ts
+var uploadTargetUrlSchema, assetMountUrlSchema;
+var init_url = __esm({
+  "../canopycms/src/config/schemas/url.ts"() {
+    "use strict";
+    init_zod();
+    init_sanitize_href();
+    uploadTargetUrlSchema = external_exports.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value), {
+      message: 'must be an absolute http(s) URL or a site-relative path beginning with a single "/", with no query or fragment'
+    });
+    assetMountUrlSchema = external_exports.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value, { allowProtocolRelative: true }), {
+      message: 'must be an absolute http(s) URL, a protocol-relative "//host" URL, or a site-relative path beginning with a single "/", with no query or fragment'
+    });
+  }
+});
+
 // ../canopycms/src/config/schemas/media.ts
 var mediaSchema;
 var init_media = __esm({
@@ -4375,25 +4435,41 @@ var init_media = __esm({
     "use strict";
     init_zod();
     init_collection();
+    init_url();
     mediaSchema = external_exports.discriminatedUnion("adapter", [
       external_exports.object({
         adapter: external_exports.literal("local"),
-        publicBaseUrl: external_exports.string().url().optional(),
+        publicBaseUrl: assetMountUrlSchema.optional(),
         /** Root directory for local asset storage. Defaults to the caller's dev-assets dir. */
         directory: relativePathSchema.optional()
-      }),
+      }).strict(),
       external_exports.object({
         adapter: external_exports.literal("s3"),
         bucket: external_exports.string().min(1),
         region: external_exports.string().min(1),
-        publicBaseUrl: external_exports.string().url().optional(),
+        publicBaseUrl: assetMountUrlSchema.optional(),
+        /**
+         * Where the browser POSTs a presigned direct upload. Absolute http(s) URL or a
+         * site-relative path; defaults to the S3 REST endpoint the AWS SDK returns.
+         *
+         * Set this to route uploads through your own CDN so they are same-origin with the
+         * editor, which removes the need for a bucket CORS rule naming an exact origin. The
+         * signature is unaffected — a presigned POST's string-to-sign is the base64 policy
+         * alone, so the host never enters it (pinned by store-s3.test.ts).
+         *
+         * NOT a prefix. Unlike `publicBaseUrl`, nothing is joined onto this value; it replaces
+         * the POST target outright and is passed through byte-for-byte. Do not route it through
+         * `joinUrlPrefix` "for consistency" — that would strip the trailing slash and silently
+         * stop a CDN path pattern like `/asset-upload/*` from matching.
+         */
+        uploadUrl: uploadTargetUrlSchema.optional(),
         /** Max upload size in bytes for presigned direct uploads. Defaults to 50 MiB. */
         maxUploadBytes: external_exports.number().int().positive().optional()
-      }),
+      }).strict(),
       external_exports.object({
         adapter: external_exports.literal("lfs"),
-        publicBaseUrl: external_exports.string().url().optional()
-      })
+        publicBaseUrl: assetMountUrlSchema.optional()
+      }).strict()
     ]);
   }
 });
@@ -28367,6 +28443,9 @@ var BLOCK_STRUCTURAL_KEYS = new Set(BLOCK_DISCRIMINATOR_KEYS);
 init_error();
 init_logger();
 
+// ../canopycms/src/utils/url-prefix.ts
+init_sanitize_href();
+
 // ../canopycms/src/static/seo.ts
 var DEFAULT_SEO_FIELD_NAMES = {
   title: "metaTitle",
@@ -30365,6 +30444,7 @@ var DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 // ../canopycms/src/assets/store-s3.ts
 var import_client_s3 = require("@aws-sdk/client-s3");
 var import_s3_presigned_post = require("@aws-sdk/s3-presigned-post");
+init_sanitize_href();
 var DEFAULT_MAX_UPLOAD_BYTES2 = 50 * 1024 * 1024;
 var PRESIGN_EXPIRY_SECONDS = 15 * 60;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-cdk",
-  "version": "0.0.66-int.84",
+  "version": "0.0.66-int.86",
   "description": "AWS CDK constructs and EC2 worker for CanopyCMS deployment",
   "license": "MIT",
   "repository": {
@@ -14,8 +14,9 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [
@@ -25,12 +26,12 @@
     "lambda/asset-transform/dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.12.0"
   },
   "peerDependencies": {
     "aws-cdk-lib": "^2.260.0",
     "constructs": "^10.0.0",
-    "canopycms": "0.0.66-int.84"
+    "canopycms": "0.0.66-int.86"
   },
   "peerDependenciesMeta": {
     "aws-cdk-lib": {
@@ -54,16 +55,16 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.66-int.84",
-    "canopycms-auth-clerk": "0.0.66-int.84"
+    "canopycms": "0.0.66-int.86",
+    "canopycms-auth-clerk": "0.0.66-int.86"
   },
   "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: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'",
+    "lint": "eslint src/ 'lambda/**/*.ts' 'canary/**/*.ts' 'worker/**/*.ts' 'test-support/**/*.ts'",
     "test": "pnpm run build:test-fixtures && vitest run",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p lambda/tsconfig.json && tsc --noEmit -p canary/tsconfig.json && tsc --noEmit -p worker/tsconfig.json"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p lambda/tsconfig.json && tsc --noEmit -p canary/tsconfig.json && tsc --noEmit -p worker/tsconfig.json && tsc --noEmit -p test-support/tsconfig.json"
   }
 }

package/worker/dist/index.js

@@ -12366,6 +12366,66 @@ var init_collection = __esm({
   }
 });
 
+// ../canopycms/src/utils/sanitize-href.ts
+function declaresScheme(url) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
+}
+function isImplicitlyOffOrigin(url) {
+  if (declaresScheme(url)) return false;
+  try {
+    return new URL(url, SENTINEL_BASE).origin !== SENTINEL_BASE;
+  } catch {
+    return false;
+  }
+}
+function isHttpUrlOrSameOriginPath(value, opts = {}) {
+  if (value === "") return false;
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 32 || code === 127) return false;
+  }
+  if (value.includes("?") || value.includes("#")) return false;
+  if (value.includes("\\")) return false;
+  if (DOT_SEGMENT.test(value)) return false;
+  if (declaresScheme(value)) {
+    if (!/^https?:\/\//i.test(value)) return false;
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  if (isImplicitlyOffOrigin(value)) {
+    return opts.allowProtocolRelative === true && value.startsWith("//") && value[2] !== "/";
+  }
+  return value.startsWith("/") && value[1] !== "/";
+}
+var SENTINEL_BASE, DOT_SEGMENT;
+var init_sanitize_href = __esm({
+  "../canopycms/src/utils/sanitize-href.ts"() {
+    "use strict";
+    SENTINEL_BASE = "https://relative.invalid";
+    DOT_SEGMENT = /(^|\/)(\.|%2e){1,2}(\/|$)/i;
+  }
+});
+
+// ../canopycms/src/config/schemas/url.ts
+var uploadTargetUrlSchema, assetMountUrlSchema;
+var init_url = __esm({
+  "../canopycms/src/config/schemas/url.ts"() {
+    "use strict";
+    init_zod();
+    init_sanitize_href();
+    uploadTargetUrlSchema = external_exports.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value), {
+      message: 'must be an absolute http(s) URL or a site-relative path beginning with a single "/", with no query or fragment'
+    });
+    assetMountUrlSchema = external_exports.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value, { allowProtocolRelative: true }), {
+      message: 'must be an absolute http(s) URL, a protocol-relative "//host" URL, or a site-relative path beginning with a single "/", with no query or fragment'
+    });
+  }
+});
+
 // ../canopycms/src/config/schemas/media.ts
 var mediaSchema;
 var init_media = __esm({
@@ -12373,25 +12433,41 @@ var init_media = __esm({
     "use strict";
     init_zod();
     init_collection();
+    init_url();
     mediaSchema = external_exports.discriminatedUnion("adapter", [
       external_exports.object({
         adapter: external_exports.literal("local"),
-        publicBaseUrl: external_exports.string().url().optional(),
+        publicBaseUrl: assetMountUrlSchema.optional(),
         /** Root directory for local asset storage. Defaults to the caller's dev-assets dir. */
         directory: relativePathSchema.optional()
-      }),
+      }).strict(),
       external_exports.object({
         adapter: external_exports.literal("s3"),
         bucket: external_exports.string().min(1),
         region: external_exports.string().min(1),
-        publicBaseUrl: external_exports.string().url().optional(),
+        publicBaseUrl: assetMountUrlSchema.optional(),
+        /**
+         * Where the browser POSTs a presigned direct upload. Absolute http(s) URL or a
+         * site-relative path; defaults to the S3 REST endpoint the AWS SDK returns.
+         *
+         * Set this to route uploads through your own CDN so they are same-origin with the
+         * editor, which removes the need for a bucket CORS rule naming an exact origin. The
+         * signature is unaffected — a presigned POST's string-to-sign is the base64 policy
+         * alone, so the host never enters it (pinned by store-s3.test.ts).
+         *
+         * NOT a prefix. Unlike `publicBaseUrl`, nothing is joined onto this value; it replaces
+         * the POST target outright and is passed through byte-for-byte. Do not route it through
+         * `joinUrlPrefix` "for consistency" — that would strip the trailing slash and silently
+         * stop a CDN path pattern like `/asset-upload/*` from matching.
+         */
+        uploadUrl: uploadTargetUrlSchema.optional(),
         /** Max upload size in bytes for presigned direct uploads. Defaults to 50 MiB. */
         maxUploadBytes: external_exports.number().int().positive().optional()
-      }),
+      }).strict(),
       external_exports.object({
         adapter: external_exports.literal("lfs"),
-        publicBaseUrl: external_exports.string().url().optional()
-      })
+        publicBaseUrl: assetMountUrlSchema.optional()
+      }).strict()
     ]);
   }
 });