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

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

@@ -96,6 +96,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
@@ -217,13 +243,17 @@ export declare class AssetSupport extends Construct {
     /** Effective advisory upload-size cap (see `AssetSupportProps.maxUploadBytes`). */
     readonly maxUploadBytes: number;
     private readonly behaviors;
-    /** Distributions `attachTo` has already wired -- see that method's duplicate check. */
-    private readonly attachedDistributions;
     constructor(scope: Construct, id: string, props: AssetSupportProps);
     private buildBehaviors;
     /**
      * The two CloudFront behavior configs this system needs.
      *
+     * If you use this rather than `attachTo` -- which now takes an `overrides`
+     * parameter, so needing per-behavior options is no longer a reason to fall
+     * back here -- you own the ordering, and you should assert it: read the
+     * SYNTHESIZED template's `CacheBehaviors` array index, not your own source
+     * object, since the property is about emitted order.
+     *
      * Prefer `attachTo(distribution)` or `CanopyCmsDistribution`'s
      * `assetSupport` prop, which attach these to a distribution in the only
      * safe order automatically. This method exists as the escape hatch for a
@@ -250,6 +280,33 @@ export declare class AssetSupport extends Construct {
      * 0x2A, `t` = 0x74), so alphabetizing the keys reproduces exactly this
      * failure, with no synth or deploy error to catch it.
      *
+     * `overrides` is merged into BOTH behaviors, and exists because without it
+     * this method is unusable by exactly the adopters who most need the ordering
+     * guarantee. A distribution that runs a viewer-request function on every
+     * behavior - tier basic-auth, most commonly - needs the asset behaviors to
+     * carry that same `functionAssociations`, or `/assets/*` is anonymously
+     * readable on an authenticated tier. Before this parameter existed such an
+     * adopter had to fall back to `assetBehaviors()` plus two hand-ordered
+     * `addBehavior` calls: the precise shape this method was added to eliminate,
+     * re-entered while believing ordering was handled upstream, which is worse
+     * than never having had the method. (`responseHeadersPolicy` is the same
+     * story for a repo with a shared security-headers policy.)
+     *
+     * Merged into both rather than per-behavior on purpose: applying one set to
+     * both is what preserves the ordering guarantee as the only thing this
+     * method decides. A caller who genuinely needs the two behaviors to differ
+     * has left this method's remit and should use `assetBehaviors()` - and keep
+     * their own ordering assertion.
+     *
+     * Typed `Partial<AddBehaviorOptions>` because that is exactly what
+     * `addBehavior(pattern, origin, behaviorOptions?)` accepts - `origin` is a
+     * POSITIONAL argument there, so `BehaviorOptions` (which is
+     * `AddBehaviorOptions` plus `origin`) would let a caller pass a key the call
+     * silently ignores. Measured, because the first version of this comment
+     * claimed the opposite: widening the parameter and passing an `origin`
+     * override changes nothing in the emitted template, so this narrowing
+     * prevents a confusing no-op rather than a broken origin group.
+     *
      * Needs a concrete `cloudfront.Distribution` - `addBehavior` is an instance
      * method on that class, not on `IDistribution` (what an imported/looked-up
      * distribution reference gives you). For a distribution built entirely
@@ -258,7 +315,7 @@ export declare class AssetSupport extends Construct {
      * directly instead and list `/assets/t/*` before `/assets/*` yourself - see
      * `AssetCloudFrontBehaviors`'s doc comment.
      */
-    attachTo(distribution: cloudfront.Distribution): void;
+    attachTo(distribution: cloudfront.Distribution, overrides?: Partial<cloudfront.AddBehaviorOptions>): void;
     /**
      * Grant the CMS/editor principal (the CMS Lambda's role, typically) the
      * exact permissions `S3AssetStore` (packages/canopycms/src/assets/store-s3.ts)

package/dist/constructs/asset-support.js

@@ -3,6 +3,7 @@ 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 { 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).
@@ -111,6 +112,24 @@ const TRANSFORM_OUTPUT_RETENTION = Duration.days(180);
 const TRANSFORM_CACHE_MIN_TTL = Duration.seconds(0);
 const TRANSFORM_CACHE_DEFAULT_TTL = Duration.days(1);
 const TRANSFORM_CACHE_MAX_TTL = Duration.days(365);
+/**
+ * Distributions that already carry the asset behaviors, tracked at MODULE level
+ * rather than per instance.
+ *
+ * Per-instance (the first version of this) only caught the same `AssetSupport`
+ * attaching twice. Two `AssetSupport` constructs attaching to one distribution
+ * slipped through and synthesized
+ * ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'] - the identical
+ * duplicate-path-pattern deploy failure the guard exists to convert into a
+ * synth error. There is no legitimate form of that: both instances attach the
+ * same two patterns, so the second is always wrong regardless of which
+ * construct owns it.
+ *
+ * A `WeakSet` keyed on the distribution object, so it holds no reference that
+ * would outlive the construct tree and cannot leak across CDK apps in a test
+ * process.
+ */
+const distributionsWithAssetBehaviors = new WeakSet();
 /**
  * The two CloudFront path patterns the asset system's behaviors are keyed
  * under, derived from `PREFIXES` above (the single source of truth for these
@@ -156,8 +175,6 @@ export const ASSET_BEHAVIOR_SPREAD_MISTAKE_KEYS = ['assets', 'assetsTransform'];
 export class AssetSupport extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
-        /** Distributions `attachTo` has already wired -- see that method's duplicate check. */
-        this.attachedDistributions = new WeakSet();
         // Fail closed before anything else: refuse to build a stack around a
         // transform Lambda whose code asset was never verified to contain the
         // linux/arm64 sharp binary. Without this, `pnpm test` (whose
@@ -241,7 +258,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
@@ -346,6 +374,12 @@ export class AssetSupport extends Construct {
     /**
      * The two CloudFront behavior configs this system needs.
      *
+     * If you use this rather than `attachTo` -- which now takes an `overrides`
+     * parameter, so needing per-behavior options is no longer a reason to fall
+     * back here -- you own the ordering, and you should assert it: read the
+     * SYNTHESIZED template's `CacheBehaviors` array index, not your own source
+     * object, since the property is about emitted order.
+     *
      * Prefer `attachTo(distribution)` or `CanopyCmsDistribution`'s
      * `assetSupport` prop, which attach these to a distribution in the only
      * safe order automatically. This method exists as the escape hatch for a
@@ -374,6 +408,33 @@ export class AssetSupport extends Construct {
      * 0x2A, `t` = 0x74), so alphabetizing the keys reproduces exactly this
      * failure, with no synth or deploy error to catch it.
      *
+     * `overrides` is merged into BOTH behaviors, and exists because without it
+     * this method is unusable by exactly the adopters who most need the ordering
+     * guarantee. A distribution that runs a viewer-request function on every
+     * behavior - tier basic-auth, most commonly - needs the asset behaviors to
+     * carry that same `functionAssociations`, or `/assets/*` is anonymously
+     * readable on an authenticated tier. Before this parameter existed such an
+     * adopter had to fall back to `assetBehaviors()` plus two hand-ordered
+     * `addBehavior` calls: the precise shape this method was added to eliminate,
+     * re-entered while believing ordering was handled upstream, which is worse
+     * than never having had the method. (`responseHeadersPolicy` is the same
+     * story for a repo with a shared security-headers policy.)
+     *
+     * Merged into both rather than per-behavior on purpose: applying one set to
+     * both is what preserves the ordering guarantee as the only thing this
+     * method decides. A caller who genuinely needs the two behaviors to differ
+     * has left this method's remit and should use `assetBehaviors()` - and keep
+     * their own ordering assertion.
+     *
+     * Typed `Partial<AddBehaviorOptions>` because that is exactly what
+     * `addBehavior(pattern, origin, behaviorOptions?)` accepts - `origin` is a
+     * POSITIONAL argument there, so `BehaviorOptions` (which is
+     * `AddBehaviorOptions` plus `origin`) would let a caller pass a key the call
+     * silently ignores. Measured, because the first version of this comment
+     * claimed the opposite: widening the parameter and passing an `origin`
+     * override changes nothing in the emitted template, so this narrowing
+     * prevents a confusing no-op rather than a broken origin group.
+     *
      * Needs a concrete `cloudfront.Distribution` - `addBehavior` is an instance
      * method on that class, not on `IDistribution` (what an imported/looked-up
      * distribution reference gives you). For a distribution built entirely
@@ -382,7 +443,7 @@ export class AssetSupport extends Construct {
      * directly instead and list `/assets/t/*` before `/assets/*` yourself - see
      * `AssetCloudFrontBehaviors`'s doc comment.
      */
-    attachTo(distribution) {
+    attachTo(distribution, overrides) {
         // `addBehavior` does not dedupe, and these calls bypass
         // `CanopyCmsDistribution`'s own synth-time guard because they run after
         // that distribution is constructed. So attaching twice -- passing the
@@ -391,18 +452,40 @@ export class AssetSupport extends Construct {
         // ['/assets/t/*','/assets/*','/assets/t/*','/assets/*'] and fails at
         // deploy time when CloudFront rejects the duplicate patterns. Refuse it
         // here instead, where the message can say which two routes collided.
-        if (this.attachedDistributions.has(distribution)) {
+        if (distributionsWithAssetBehaviors.has(distribution)) {
             throw new Error(`AssetSupport: attachTo() was already called for this distribution. Each pattern ` +
                 `would be attached twice and CloudFront rejects duplicate path patterns at deploy ` +
                 `time. This usually means the distribution was given CanopyCmsDistribution's ` +
                 `\`assetSupport\` prop (which calls attachTo for you) as well as an explicit ` +
                 `attachTo() call -- keep one.`);
         }
-        this.attachedDistributions.add(distribution);
+        distributionsWithAssetBehaviors.add(distribution);
+        // Drop explicitly-`undefined` keys before merging. A spread copies own
+        // enumerable keys INCLUDING ones whose value is undefined, so
+        // `{ ...transformRest, ...{ cachePolicy: undefined } }` deletes the
+        // construct's choice and lets CDK substitute its own default - which is a
+        // DIFFERENT default. Measured: `cachePolicy: undefined` swaps this
+        // behavior's custom policy (TRANSFORM_CACHE_MIN_TTL = 0, which exists
+        // solely to stop the oversized-output redirect loop documented above) for
+        // the managed CACHING_OPTIMIZED and its 1-second min TTL; and
+        // `viewerProtocolPolicy: undefined` downgrades BOTH behaviors from
+        // redirect-to-https to allow-all, serving assets over plain HTTP.
+        //
+        // This is not a contrived input - it is what forwarding optional props
+        // produces: `attachTo(dist, { cachePolicy: props.maybePolicy })` with the
+        // prop unset. It typechecks (every AddBehaviorOptions field is already
+        // optional), synthesizes and deploys clean.
+        const definedOverrides = Object.fromEntries(Object.entries(overrides ?? {}).filter(([, value]) => value !== undefined));
         const { origin: transformOrigin, ...transformRest } = this.behaviors.assetsTransform;
         const { origin: assetsOrigin, ...assetsRest } = this.behaviors.assets;
-        distribution.addBehavior(ASSETS_TRANSFORM_PATH_PATTERN, transformOrigin, transformRest);
-        distribution.addBehavior(ASSETS_PATH_PATTERN, assetsOrigin, assetsRest);
+        distribution.addBehavior(ASSETS_TRANSFORM_PATH_PATTERN, transformOrigin, {
+            ...transformRest,
+            ...definedOverrides,
+        });
+        distribution.addBehavior(ASSETS_PATH_PATTERN, assetsOrigin, {
+            ...assetsRest,
+            ...definedOverrides,
+        });
     }
     /**
      * Grant the CMS/editor principal (the CMS Lambda's role, typically) the

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

@@ -66,9 +66,15 @@ export interface CanopyCmsDistributionProps {
      * Attach `AssetSupport`'s CloudFront behaviors (`/assets/*` and
      * `/assets/t/*`) to the distribution this construct builds, in the only
      * safe order - see `AssetSupport.attachTo()`'s doc comment for why the
-     * order matters. Equivalent to calling
-     * `assetSupport.attachTo(distribution)` yourself right after construction,
-     * but with nothing to forget.
+     * order matters. Calls `assetSupport.attachTo(distribution)` for you right
+     * after construction, with nothing to forget.
+     *
+     * NOT fully equivalent to calling `attachTo` yourself: this path cannot pass
+     * that method's `overrides` argument. If the asset behaviors need
+     * per-behavior options - a viewer-request function for tier auth being the
+     * motivating case, since without it `/assets/*` is anonymously readable on
+     * an authenticated tier - drop this prop and call
+     * `assetSupport.attachTo(this.distribution, { ... })` after construction.
      *
      * Prefer this over passing `assetSupport.assetBehaviors()` through
      * `additionalBehaviors` by hand - that stays available as an escape hatch

package/dist/constructs/cms-distribution.js

@@ -20,7 +20,21 @@ import { ASSETS_PATH_PATTERN, ASSETS_TRANSFORM_PATH_PATTERN, ASSET_BEHAVIOR_SPRE
 function mergeBehaviors(defaults, caller, attachingAssetSupport) {
     if (!caller)
         return defaults;
-    const uncollided = Object.fromEntries(Object.entries(defaults).filter(([pattern]) => !(pattern in caller)));
+    // Compare NORMALIZED keys here too. CloudFront treats a leading '/' as
+    // optional, so a caller passing `'_next/static/*'` did not displace this
+    // construct's own `'/_next/static/*'` default and both were emitted -- two
+    // behaviors CloudFront reads as the same pattern, which it rejects at
+    // deploy. Same reason the hazard checks below normalize.
+    const callerPatterns = new Set(Object.keys(caller).map(normalizePathPattern));
+    const uncollided = Object.fromEntries(Object.entries(defaults).filter(([pattern]) => !callerPatterns.has(normalizePathPattern(pattern))));
+    const normalizedCallerKeys = Object.keys(caller).map(normalizePathPattern);
+    const duplicateCallerPattern = normalizedCallerKeys.find((pattern, i) => normalizedCallerKeys.indexOf(pattern) !== i);
+    if (duplicateCallerPattern !== undefined) {
+        throw new Error(`CanopyCmsDistribution: additionalBehaviors has two keys that CloudFront reads as the ` +
+            `same path pattern (${JSON.stringify(duplicateCallerPattern)} with and without its ` +
+            `leading '/'). CloudFront rejects duplicate path patterns at deploy time. Keep one ` +
+            `spelling.`);
+    }
     const merged = { ...uncollided, ...caller };
     assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport);
     return merged;
@@ -68,6 +82,7 @@ function mergeBehaviors(defaults, caller, attachingAssetSupport) {
 function normalizePathPattern(pattern) {
     return pattern.startsWith('/') ? pattern.slice(1) : pattern;
 }
+/** See the three-hazard list documented above `normalizePathPattern`. */
 function assertNoAssetBehaviorOrderingHazards(merged, attachingAssetSupport) {
     const keys = Object.keys(merged).map(normalizePathPattern);
     const assetsPattern = normalizePathPattern(ASSETS_PATH_PATTERN);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopycms-cdk",
-  "version": "0.0.66-int.83",
+  "version": "0.0.66-int.85",
   "description": "AWS CDK constructs and EC2 worker for CanopyCMS deployment",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
   "peerDependencies": {
     "aws-cdk-lib": "^2.260.0",
     "constructs": "^10.0.0",
-    "canopycms": "0.0.66-int.83"
+    "canopycms": "0.0.66-int.85"
   },
   "peerDependenciesMeta": {
     "aws-cdk-lib": {
@@ -54,16 +54,16 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.3",
     "vitest": "^4.1.0",
-    "canopycms": "0.0.66-int.83",
-    "canopycms-auth-clerk": "0.0.66-int.83"
+    "canopycms-auth-clerk": "0.0.66-int.85",
+    "canopycms": "0.0.66-int.85"
   },
   "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"
   }
 }