canopycms-cdk 0.0.66-int.84 → 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

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).
@@ -257,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

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.84",
+  "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.84"
+    "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.84",
-    "canopycms-auth-clerk": "0.0.66-int.84"
+    "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"
   }
 }