@aws/nx-plugin 1.0.0-rc.4 → 1.0.0-rc.41

package/src/utils/api-constructs/files/cdk/core/api/rest/api-gateway-account/index.js.template

@@ -0,0 +1,70 @@
+/**
+ * Configures the account-level API Gateway CloudWatch Logs role required for
+ * REST API access logging. The setting is a singleton per region per account,
+ * so this handler only writes when no live role is already configured (the
+ * first stack to deploy wins, others defer) and never resets it on delete.
+ */
+const {
+  APIGatewayClient,
+  GetAccountCommand,
+  UpdateAccountCommand,
+} = require('@aws-sdk/client-api-gateway');
+const { IAMClient, GetRoleCommand } = require('@aws-sdk/client-iam');
+
+const apigw = new APIGatewayClient();
+const iam = new IAMClient();
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const RETRYABLE = ['BadRequestException', 'TooManyRequestsException'];
+
+// Throttling may surface as a bare 429 with no modeled error code, so check
+// response metadata as well as error names
+const isRetryable = (e) =>
+  RETRYABLE.includes(e.name) ||
+  e.$metadata?.httpStatusCode === 429 ||
+  e.$retryable?.throttling === true;
+
+// Retry while the freshly created role propagates through IAM, and on
+// throttling of the account-level API (shared across concurrent deployments)
+const send = async (command) => {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await apigw.send(command);
+    } catch (e) {
+      if (isRetryable(e) && attempt < 11) {
+        await sleep(5000);
+      } else {
+        throw e;
+      }
+    }
+  }
+};
+
+const hasLiveRole = async () => {
+  const { cloudwatchRoleArn } = await send(new GetAccountCommand({}));
+  if (!cloudwatchRoleArn) return false;
+  try {
+    await iam.send(
+      new GetRoleCommand({ RoleName: cloudwatchRoleArn.split('/').pop() }),
+    );
+    return true;
+  } catch (e) {
+    if (e.name === 'NoSuchEntityException') return false;
+    throw e;
+  }
+};
+
+const setRole = (value) =>
+  send(
+    new UpdateAccountCommand({
+      patchOperations: [{ op: 'replace', path: '/cloudwatchRoleArn', value }],
+    }),
+  );
+
+exports.handler = async (event) => {
+  if (event.RequestType !== 'Delete' && !(await hasLiveRole())) {
+    await setRole(event.ResourceProperties.CloudWatchRoleArn);
+  }
+  return { PhysicalResourceId: 'ApiGatewayAccount' };
+};

package/src/utils/api-constructs/files/cdk/core/api/rest/api-gateway-account.ts.template

@@ -0,0 +1,82 @@
+import { Construct } from 'constructs';
+import * as url from 'url';
+import { CustomResource, Duration, RemovalPolicy, Stack } from 'aws-cdk-lib';
+import {
+  ManagedPolicy,
+  PolicyStatement,
+  Role,
+  ServicePrincipal,
+} from 'aws-cdk-lib/aws-iam';
+import { Code, Function, Runtime } from 'aws-cdk-lib/aws-lambda';
+import { Provider } from 'aws-cdk-lib/custom-resources';
+
+const ApiGatewayAccountKey = '__ApiGatewayAccount__';
+
+/**
+ * Stack-scoped singleton that configures the account-level CloudWatch Logs role
+ * used by API Gateway REST APIs for access logging.
+ *
+ * `AWS::ApiGateway::Account` is a singleton per region per account, so it is
+ * managed via an idempotent custom resource: the role is set only when none is
+ * already configured, and is never reset on delete. This keeps logging working
+ * across multiple stacks sharing an account without one clobbering another.
+ */
+export class ApiGatewayAccount extends Construct {
+  static ensure(scope: Construct): ApiGatewayAccount {
+    const stack = Stack.of(scope);
+    return (
+      (stack.node.tryFindChild(ApiGatewayAccountKey) as ApiGatewayAccount) ??
+      new ApiGatewayAccount(stack, ApiGatewayAccountKey)
+    );
+  }
+
+  public readonly resource: CustomResource;
+
+  private constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    const cloudWatchRole = new Role(this, 'CloudWatchRole', {
+      assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
+      managedPolicies: [
+        ManagedPolicy.fromAwsManagedPolicyName(
+          'service-role/AmazonAPIGatewayPushToCloudWatchLogs',
+        ),
+      ],
+    });
+    cloudWatchRole.applyRemovalPolicy(RemovalPolicy.RETAIN);
+
+    const onEvent = new Function(this, 'OnEvent', {
+      runtime: Runtime.NODEJS_LATEST,
+      handler: 'index.handler',
+      timeout: Duration.minutes(2),
+      code: Code.fromAsset(
+        url.fileURLToPath(new URL('./api-gateway-account', <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>)),
+      ),
+    });
+    const { region } = Stack.of(this);
+    onEvent.addToRolePolicy(
+      new PolicyStatement({
+        actions: ['apigateway:GET', 'apigateway:PATCH'],
+        resources: [`arn:aws:apigateway:${region}::/account`],
+      }),
+    );
+    onEvent.addToRolePolicy(
+      new PolicyStatement({
+        actions: ['iam:PassRole'],
+        resources: [cloudWatchRole.roleArn],
+      }),
+    );
+    // Read-only; inspects whichever role the account currently references
+    onEvent.addToRolePolicy(
+      new PolicyStatement({ actions: ['iam:GetRole'], resources: ['*'] }),
+    );
+
+    this.resource = new CustomResource(this, 'Resource', {
+      serviceToken: new Provider(this, 'Provider', { onEventHandler: onEvent })
+        .serviceToken,
+      resourceType: 'Custom::ApiGatewayAccount',
+      properties: { CloudWatchRoleArn: cloudWatchRole.roleArn },
+    });
+    this.resource.node.addDependency(cloudWatchRole);
+  }
+}

package/src/utils/api-constructs/files/cdk/core/api/rest/rest-api.ts.template

@@ -1,26 +1,32 @@
 import { Construct, IConstruct } from 'constructs';
 import {
+  AccessLogFormat,
   Cors,
+  LogGroupLogDestination,
   Resource,
   RestApi as _RestApi,
   RestApiProps as _RestApiProps,
   IResource,
   Stage,
+  ThrottleSettings,
 } from 'aws-cdk-lib/aws-apigateway';
-import { IAspect, RemovalPolicy } from 'aws-cdk-lib';
+import { IAspect, Stack } from 'aws-cdk-lib';
 import {
   CfnLoggingConfiguration,
   CfnWebACL,
   CfnWebACLAssociation,
 } from 'aws-cdk-lib/aws-wafv2';
 import { LogGroup, RetentionDays } from 'aws-cdk-lib/aws-logs';
-import { RuntimeConfig } from '../runtime-config.js';
+import { Key } from 'aws-cdk-lib/aws-kms';
+import { ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+import { RuntimeConfig } from '../runtime-config<% if (esm) { %>.js<% } %>';
+import { ApiGatewayAccount } from './api-gateway-account<% if (esm) { %>.js<% } %>';
 import {
   ApiIntegrations,
   OperationDetails,
   RestApiIntegration,
-} from './utils.js';
-import { suppressRules } from '../checkov.js';
+} from './utils<% if (esm) { %>.js<% } %>';
+import { suppressRules } from '../checkov<% if (esm) { %>.js<% } %>';
 
 /**
  * Properties for creating a RestApi construct.
@@ -52,6 +58,12 @@ export interface RestApiProps<
    * @default true
    */
   readonly enableWaf?: boolean;
+  /**
+   * Default throttling limits applied to all methods on the API's default stage.
+   *
+   * @default { rateLimit: 10000, burstLimit: 5000 }
+   */
+  readonly throttle?: ThrottleSettings;
 }
 
 /**
@@ -86,14 +98,49 @@ export class RestApi<
       operations,
       integrations,
       enableWaf = true,
+      throttle = { rateLimit: 10000, burstLimit: 5000 },
       ...props
     }: RestApiProps<TIntegrations, TOperation>,
   ) {
     super(scope, id);
     this.integrations = integrations;
 
+    // Account-level CloudWatch role required for REST API access logging
+    const account = ApiGatewayAccount.ensure(this);
+
+    // KMS key for encrypting logs at rest, usable by CloudWatch Logs
+    const logsKey = new Key(this, 'LogsKey', {
+      enableKeyRotation: true,
+    });
+    logsKey.grantEncryptDecrypt(
+      new ServicePrincipal(`logs.${Stack.of(this).region}.amazonaws.com`),
+    );
+
+    const accessLogs = new LogGroup(this, 'AccessLogs', {
+      retention: RetentionDays.ONE_YEAR,
+      encryptionKey: logsKey,
+    });
+
     // Create the API Gateway REST API
-    this.api = new _RestApi(this, 'Api', props);
+    this.api = new _RestApi(this, 'Api', {
+      ...props,
+      deployOptions: {
+        accessLogDestination: new LogGroupLogDestination(accessLogs),
+        accessLogFormat: AccessLogFormat.jsonWithStandardFields(),
+        ...props.deployOptions,
+        methodOptions: {
+          ...props.deployOptions?.methodOptions,
+          // Default throttling applied to all resource paths and methods
+          '/*/*': {
+            throttlingRateLimit: throttle.rateLimit,
+            throttlingBurstLimit: throttle.burstLimit,
+            ...props.deployOptions?.methodOptions?.['/*/*'],
+          },
+        },
+      },
+    });
+    // Ensure the account-level role is configured before the stage is created
+    this.api.deploymentStage.node.addDependency(account.resource);
 
     if (enableWaf) {
       this.webAcl = new CfnWebACL(this, 'WebAcl', {
@@ -160,14 +207,9 @@ export class RestApi<
       // `aws-waf-logs-` to satisfy the WAFv2 logging destination requirement.
       const wafLogGroup = new LogGroup(this, 'WebAclLogs', {
         logGroupName: `aws-waf-logs-${apiName}-${this.node.addr.slice(-8)}`,
-        retention: RetentionDays.ONE_MONTH,
-        removalPolicy: RemovalPolicy.DESTROY,
+        retention: RetentionDays.ONE_YEAR,
+        encryptionKey: logsKey,
       });
-      suppressRules(
-        wafLogGroup,
-        ['CKV_AWS_158'],
-        'Using default CloudWatch log encryption for WAF logs',
-      );
 
       new CfnLoggingConfiguration(this, 'WebAclLoggingConfig', {
         resourceArn: this.webAcl.attrArn,
@@ -181,12 +223,6 @@ export class RestApi<
       'Caching not required for this use case',
       (c) => c instanceof Stage,
     );
-    suppressRules(
-      this.api,
-      ['CKV_AWS_76'],
-      'API Gateway access logging disabled due to account-level CloudWatch Logs role ARN requirement',
-      (c) => c instanceof Stage,
-    );
 
     // Resolve the integration for a given operation.
     // If the operation has a dedicated integration, use it; otherwise fall back to $router.

package/src/utils/api-constructs/files/cdk/core/api/trpc/trpc-utils.ts.template

@@ -1,5 +1,5 @@
 import { TRPCRouterRecord, AnyTRPCRouter } from '@trpc/server';
-import { OperationDetails } from './utils.js';
+import { OperationDetails } from './utils<% if (esm) { %>.js<% } %>';
 import { HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
 
 /**

package/src/utils/api-constructs/files/cdk/core/api/utils/utils.ts.template

@@ -148,6 +148,8 @@ export type ApiIntegrations<TOperation extends string, TBaseIntegration> =
  * @template TDefaultIntegrationProps - Type for default integration properties
  * @template TDefaultIntegration - Type for default integration implementation
  * @template TPattern - The integration pattern ('shared' or 'isolated')
+ * @template TOverridden - Union of operation names that have been overridden
+ * @template TOperationOptioned - Union of operation names with per-operation options
  */
 export class IntegrationBuilder<
   TOperation extends string,
@@ -156,6 +158,8 @@ export class IntegrationBuilder<
   TDefaultIntegrationProps extends object,
   TDefaultIntegration extends TBaseIntegration,
   TPattern extends 'shared' | 'isolated',
+  TOverridden extends string = never,
+  TOperationOptioned extends string = never,
 > {
   /** Options for the integration builder */
   private options: IntegrationBuilderProps<
@@ -168,6 +172,11 @@ export class IntegrationBuilder<
   /** Map of operation names to their custom integrations */
   private integrations: Partial<TIntegrations> = {};
 
+  /** Map of default integration keys to per-operation default option overrides */
+  private perOperationOptions: Partial<
+    Record<string, Partial<TDefaultIntegrationProps>>
+  > = {};
+
   /**
    * Create an Integration Builder for an HTTP API with a shared pattern
    */
@@ -322,11 +331,16 @@ export class IntegrationBuilder<
   /**
    * Overrides default integrations with custom implementations for specific operations.
    *
+   * Operations which have per-operation options set via withOperationOptions cannot be
+   * overridden, since these still use the default integration.
+   *
    * @param overrides - Map of operation names to their custom integration implementations
    * @returns The builder instance with updated type information reflecting the overrides
    */
   public withOverrides<
-    TOverrideIntegrations extends Partial<Record<TOperation, TBaseIntegration>>,
+    TOverrideIntegrations extends Partial<
+      Record<Exclude<TOperation, TOperationOptioned>, TBaseIntegration>
+    >,
   >(overrides: TOverrideIntegrations) {
     this.integrations = { ...this.integrations, ...overrides };
     // Re-type to include the overridden integration types.
@@ -342,7 +356,9 @@ export class IntegrationBuilder<
       MergedIntegrations,
       TDefaultIntegrationProps,
       TDefaultIntegration,
-      TPattern
+      TPattern,
+      TOverridden | Extract<keyof TOverrideIntegrations, string>,
+      TOperationOptioned
     >;
   }
 
@@ -361,6 +377,43 @@ export class IntegrationBuilder<
     return this;
   }
 
+  /**
+   * Updates the default integration options for specific operations, without
+   * affecting the others. The given options are merged with the defaults (and
+   * any options set via withDefaultOptions) when building each default integration.
+   *
+   * Operations which have been replaced via withOverrides cannot be targeted, since
+   * they no longer use the default integration.
+   *
+   * @param options - Map of operation names to partial default integration options
+   * @returns The builder instance
+   */
+  public withOperationOptions<
+    TOptions extends Partial<
+      Record<
+        Exclude<DefaultIntegrationKeys<TPattern, TOperation>, TOverridden>,
+        Partial<TDefaultIntegrationProps>
+      >
+    >,
+  >(options: TOptions) {
+    Object.entries(options).forEach(([op, opOptions]) => {
+      this.perOperationOptions[op] = {
+        ...this.perOperationOptions[op],
+        ...(opOptions as Partial<TDefaultIntegrationProps>),
+      };
+    });
+    return this as unknown as IntegrationBuilder<
+      TOperation,
+      TBaseIntegration,
+      TIntegrations,
+      TDefaultIntegrationProps,
+      TDefaultIntegration,
+      TPattern,
+      TOverridden,
+      TOperationOptioned | Extract<keyof TOptions, string>
+    >;
+  }
+
   /**
    * Builds and returns the complete set of integrations.
    *
@@ -375,6 +428,10 @@ export class IntegrationBuilder<
    */
   public build(): TIntegrations {
     const options = this.options;
+    const buildOptionsFor = (op: string): TDefaultIntegrationProps => ({
+      ...options.defaultIntegrationOptions,
+      ...this.perOperationOptions[op],
+    });
     return {
       ...Object.fromEntries(
         options.pattern === 'shared'
@@ -383,7 +440,7 @@ export class IntegrationBuilder<
                 '$router',
                 options.buildDefaultIntegration(
                   '$router',
-                  options.defaultIntegrationOptions,
+                  buildOptionsFor('$router'),
                 ),
               ],
             ]
@@ -394,10 +451,7 @@ export class IntegrationBuilder<
               )
               .map((op) => [
                 op,
-                options.buildDefaultIntegration(
-                  op,
-                  options.defaultIntegrationOptions,
-                ),
+                options.buildDefaultIntegration(op, buildOptionsFor(op)),
               ]),
       ),
       ...this.integrations,

package/src/utils/api-constructs/files/terraform/app/apis/http/__apiNameKebabCase__/__apiNameKebabCase__.tf.template

@@ -4,7 +4,7 @@ terraform {
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = "~> 6.0"
+      version = "<%- awsProviderVersion %>"
     }
   }
 }
@@ -38,11 +38,47 @@ variable "additional_iam_policy_statements" {
   default = []
 }
 
+variable "appconfig_application_id" {
+  description = "ID of the shared runtime-config AppConfig application (from `core/runtime-config/appconfig.application_id`). When set, the Lambda functions receive `RUNTIME_CONFIG_APP_ID` and read access to the application."
+  type        = string
+  default     = null
+}
+
+variable "appconfig_application_arn" {
+  description = "ARN of the shared runtime-config AppConfig application (from `core/runtime-config/appconfig.application_arn`). Used to scope the IAM read permission granted to the Lambda functions."
+  type        = string
+  default     = null
+}
+
 variable "asset_bucket_name" {
   description = "Name of the shared asset S3 bucket used to stage the Lambda deployment zip. Instantiate the `core/asset-bucket` module once per deployment and pass its `bucket_name` output here."
   type        = string
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Deploy the Lambda function into a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to deploy the Lambda function into. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 # CORS Configuration (passed to core module)
 variable "cors_allow_credentials" {
   description = "Whether to allow credentials in CORS requests"
@@ -74,12 +110,6 @@ variable "cors_expose_headers" {
   default     = []
 }
 
-variable "cors_max_age" {
-  description = "Maximum age for CORS preflight requests in seconds"
-  type        = number
-  default     = 0
-}
-
 # Tags
 variable "tags" {
   description = "Tags to apply to all resources"
@@ -130,16 +160,37 @@ module "http_api" {
   cors_allow_methods     = var.cors_allow_methods
   cors_allow_origins     = var.cors_allow_origins
   cors_expose_headers    = var.cors_expose_headers
-  cors_max_age           = var.cors_max_age
 
   # Tags
   tags = var.tags
 }
 
+# Security group for the API Lambda function, used when deployed into a VPC
+resource "aws_security_group" "api_lambda" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to api_lambda via vpc_config block; Checkov cannot resolve this reference
+  name_prefix = "<%- apiNameKebabCase %>-lambda-"
+  description = "Security group for the <%- apiNameClassName %> API Lambda function"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_lambda_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.api_lambda[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Lambda function
 # This configures a single "router" lambda to serve all requests
 resource "aws_lambda_function" "api_lambda" {
-  #checkov:skip=CKV_AWS_117:Lambda function does not need to be in VPC for this use case
+  #checkov:skip=CKV_AWS_117:Lambda function is optionally deployed into a VPC via vpc_id/subnet_ids; not required for this use case
   #checkov:skip=CKV_AWS_116:Dead Letter Queue not required for this simple API use case
   #checkov:skip=CKV_AWS_272:Code signing not required for this use case
   #checkov:skip=CKV_AWS_115:Concurrent execution limit not required for this use case
@@ -170,6 +221,14 @@ resource "aws_lambda_function" "api_lambda" {
     mode = "Active"
   }
 
+  dynamic "vpc_config" {
+    for_each = var.enable_vpc ? [1] : []
+    content {
+      subnet_ids         = var.subnet_ids
+      security_group_ids = [aws_security_group.api_lambda[0].id]
+    }
+  }
+
   <%_ if (backend.type === 'fastapi') { _%>
   # Enable SnapStart for faster cold starts
   snap_start {
@@ -184,10 +243,14 @@ resource "aws_lambda_function" "api_lambda" {
       AWS_LWA_INVOKE_MODE         = "buffered"
       AWS_LAMBDA_EXEC_WRAPPER     = "/opt/bootstrap"
       <%_ } _%>
-    }, var.env)
+    }, var.appconfig_application_id != null ? {
+      RUNTIME_CONFIG_APP_ID = var.appconfig_application_id
+    } : {}, var.env)
   }
 
   tags = var.tags
+
+  depends_on = [aws_iam_role_policy_attachment.lambda_vpc_access]
 }
 
 # IAM role for Lambda execution
@@ -222,18 +285,39 @@ resource "aws_iam_role_policy_attachment" "lambda_xray_execution" {
   role       = aws_iam_role.lambda_execution_role.name
 }
 
+# Attach VPC access policy to Lambda role when deployed into a VPC
+resource "aws_iam_role_policy_attachment" "lambda_vpc_access" {
+  count      = var.enable_vpc ? 1 : 0
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
+  role       = aws_iam_role.lambda_execution_role.name
+}
+
 # Additional IAM policies for Lambda (if provided)
 resource "aws_iam_role_policy" "lambda_additional_policies" {
-  count = length(var.additional_iam_policy_statements) > 0 ? 1 : 0
+  count = length(local.lambda_policy_statements) > 0 ? 1 : 0
   name  = "<%- apiNameClassName %>Handler-additional-policies-${random_string.suffix.result}"
   role  = aws_iam_role.lambda_execution_role.id
 
   policy = jsonencode({
     Version = "2012-10-17"
-    Statement = var.additional_iam_policy_statements
+    Statement = local.lambda_policy_statements
   })
 }
 
+locals {
+  # Grant read access to the runtime-config AppConfig application when wired
+  lambda_policy_statements = concat(var.appconfig_application_arn != null ? [
+    {
+      Effect = "Allow"
+      Action = [
+        "appconfig:StartConfigurationSession",
+        "appconfig:GetLatestConfiguration"
+      ]
+      Resource = ["${var.appconfig_application_arn}/*"]
+    }
+  ] : [], var.additional_iam_policy_statements)
+}
+
 # CloudWatch Log Group for Lambda
 resource "aws_cloudwatch_log_group" "lambda_logs" {
   #checkov:skip=CKV_AWS_158:Using default CloudWatch log encryption
@@ -534,6 +618,11 @@ output "lambda_execution_role_name" {
   value       = aws_iam_role.lambda_execution_role.name
 }
 
+output "security_group_id" {
+  description = "Security group ID of the API Lambda function, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.api_lambda[0].id : null
+}
+
 # Integration Outputs
 output "integration_id" {
   description = "ID of the Lambda integration"