New: [AEA-6258] - Add SSM Parameter construct

packages/cdkConstructs/src/config/index.ts

@@ -2,21 +2,36 @@ import {CloudFormationClient, DescribeStacksCommand} from "@aws-sdk/client-cloud
 import {S3Client, HeadObjectCommand} from "@aws-sdk/client-s3"
 import {StandardStackProps} from "../apps/createApp"
 
-export function getConfigFromEnvVar(varName: string, prefix: string = "CDK_CONFIG_"): string {
+export function getConfigFromEnvVar(
+  varName: string,
+  prefix: string = "CDK_CONFIG_",
+  defaultValue: string | undefined = undefined
+): string {
   const value = process.env[prefix + varName]
   if (!value) {
+    if (defaultValue !== undefined) {
+      return defaultValue
+    }
     throw new Error(`Environment variable ${prefix}${varName} is not set`)
   }
   return value
 }
 
-export function getBooleanConfigFromEnvVar(varName: string, prefix: string = "CDK_CONFIG_"): boolean {
-  const value = getConfigFromEnvVar(varName, prefix)
+export function getBooleanConfigFromEnvVar(
+  varName: string,
+  prefix: string = "CDK_CONFIG_",
+  defaultValue: string | undefined = undefined
+): boolean {
+  const value = getConfigFromEnvVar(varName, prefix, defaultValue)
   return value.toLowerCase().trim() === "true"
 }
 
-export function getNumberConfigFromEnvVar(varName: string, prefix: string = "CDK_CONFIG_"): number {
-  const value = getConfigFromEnvVar(varName, prefix)
+export function getNumberConfigFromEnvVar(
+  varName: string,
+  prefix: string = "CDK_CONFIG_",
+  defaultValue: string | undefined = undefined
+): number {
+  const value = getConfigFromEnvVar(varName, prefix, defaultValue)
   return Number(value)
 }
 

packages/cdkConstructs/src/constructs/RestApiGateway/StateMachineEndpoint.ts

@@ -63,9 +63,9 @@ export class StateMachineEndpoint extends Construct {
       ]
     }), {
       methodResponses: [
-        { statusCode: "200" },
-        { statusCode: "400" },
-        { statusCode: "500" }
+        {statusCode: "200"},
+        {statusCode: "400"},
+        {statusCode: "500"}
       ]
     })
 

packages/cdkConstructs/src/constructs/RestApiGateway/templates/stateMachineRequest.ts

@@ -3,7 +3,7 @@
  * @returns API Gateway request mapping template for StartExecution payloads.
  */
 export const stateMachineRequestTemplate = (stateMachineArn: string) => {
-  return `## Velocity Template used for API Gateway request mapping template
+    return `## Velocity Template used for API Gateway request mapping template
 ## "@@" is used here as a placeholder for '"' to avoid using escape characters.
 
 #set($includeHeaders = true)

packages/cdkConstructs/src/constructs/SsmParametersConstruct.ts

@@ -0,0 +1,172 @@
+import {CfnOutput} from "aws-cdk-lib"
+import {Effect, ManagedPolicy, PolicyStatement} from "aws-cdk-lib/aws-iam"
+import {StringParameter} from "aws-cdk-lib/aws-ssm"
+import {Construct} from "constructs"
+
+/**
+ * Definition for a single SSM String parameter and its output export metadata.
+ *
+ * @property id Unique identifier used for construct and output logical IDs.
+ * @property nameSuffix Suffix appended to stackName to create the parameter name.
+ * The final SSM parameter name is `${stackName}-${nameSuffix}`.
+ * @property description Description stored with the SSM parameter.
+ * @property value Value stored in the SSM parameter.
+ * @property outputExportSuffix Optional export suffix for the output containing
+ * the parameter name. Defaults to `nameSuffix`.
+ * @property outputDescription Optional output description. Defaults to
+ * `description`.
+ */
+export interface SsmParameterDefinition {
+  /**
+   * Unique identifier used for construct and output logical IDs.
+   */
+  readonly id: string
+  /**
+   * Suffix appended to stackName to create the parameter name.
+   * The final SSM parameter name is `${stackName}-${nameSuffix}`.
+   */
+  readonly nameSuffix: string
+  /**
+   * Description stored with the SSM parameter.
+   */
+  readonly description: string
+  /**
+   * Value stored in the SSM parameter.
+   */
+  readonly value: string
+  /**
+   * Optional export suffix for the output containing the parameter name.
+   * @default nameSuffix value
+   */
+  readonly outputExportSuffix?: string
+  /**
+   * Optional output description.
+   * @default description value
+   */
+  readonly outputDescription?: string
+}
+
+/**
+ * Properties used to configure {@link SsmParametersConstruct}.
+ *
+ * @property namePrefix Prefix used in SSM parameter names and CloudFormation
+ * export names.
+ * @property parameters List of SSM parameters to create.
+ * @property readPolicyDescription Description for the managed policy that grants
+ * read access. Defaults to "Allows reading SSM parameters".
+ * @property readPolicyOutputDescription Description for the output exporting the
+ * managed policy ARN. Defaults to "Access to the parameters used by the integration".
+ * @property readPolicyExportSuffix Export suffix for the output exporting the
+ * managed policy ARN.
+ */
+export interface SsmParametersConstructProps {
+  /**
+   * Prefix used in SSM parameter names and CloudFormation export names.
+   */
+  readonly namePrefix: string
+  /**
+   * List of SSM parameters to create.
+   */
+  readonly parameters: Array<SsmParameterDefinition>
+  /**
+   * Description for the managed policy that grants read access.
+   * @default "Allows reading SSM parameters"
+   */
+  readonly readPolicyDescription?: string
+  /**
+   * Description for the output exporting the managed policy ARN.
+   * @default "Access to the parameters used by the integration"
+   */
+  readonly readPolicyOutputDescription?: string
+  /**
+   * Export suffix for the output exporting the managed policy ARN.
+   */
+  readonly readPolicyExportSuffix: string
+}
+
+/**
+ * Creates a bundle of SSM String parameters, a managed policy to read them,
+ * and CloudFormation outputs to export parameter names and policy ARN.
+ */
+export class SsmParametersConstruct extends Construct {
+  public readonly parameters: Record<string, StringParameter>
+  public readonly readParametersPolicy: ManagedPolicy
+
+  /**
+   * Creates SSM String parameters, a managed read policy, and CloudFormation outputs.
+   *
+   * @param scope CDK construct scope.
+   * @param id Unique construct identifier.
+   * @param props Configuration for parameter names, values, and exported outputs.
+   * @throws {Error} Throws when no parameter definitions are provided.
+   * @throws {Error} Throws when duplicate parameter IDs or parameter names are detected.
+   */
+  public constructor(scope: Construct, id: string, props: SsmParametersConstructProps) {
+    super(scope, id)
+
+    const {
+      namePrefix: stackName,
+      parameters,
+      readPolicyExportSuffix,
+      readPolicyDescription = "Allows reading SSM parameters",
+      readPolicyOutputDescription = "Access to the parameters used by the integration"
+    } = props
+
+    if (parameters.length === 0) {
+      throw new Error("SsmParametersConstruct requires at least one parameter definition")
+    }
+
+    const createdParameters: Record<string, StringParameter> = {}
+
+    const seenIds = new Set<string>()
+    const seenNames = new Set<string>()
+
+    for (const parameter of parameters) {
+      const parameterId = `${parameter.id}Parameter`
+      if (seenIds.has(parameterId)) {
+        throw new Error(`Duplicate parameter id detected: ${parameter.id}.`)
+      }
+      seenIds.add(parameterId)
+
+      const parameterName = `${stackName}-${parameter.nameSuffix}`
+      if (seenNames.has(parameterName)) {
+        throw new Error(`Duplicate parameter name detected: ${parameterName}.`)
+      }
+      seenNames.add(parameterName)
+
+      const ssmParameter = new StringParameter(this, parameterId, {
+        parameterName,
+        description: parameter.description,
+        stringValue: parameter.value
+      })
+
+      createdParameters[parameter.id] = ssmParameter
+
+      new CfnOutput(this, `${parameter.id}ParameterNameOutput`, {
+        description: parameter.outputDescription ?? parameter.description,
+        value: ssmParameter.parameterName,
+        exportName: `${stackName}-${parameter.outputExportSuffix ?? parameter.nameSuffix}`
+      })
+    }
+
+    const readParametersPolicy = new ManagedPolicy(this, "GetParametersPolicy", {
+      description: readPolicyDescription,
+      statements: [
+        new PolicyStatement({
+          effect: Effect.ALLOW,
+          actions: ["ssm:GetParameter", "ssm:GetParameters"],
+          resources: Object.values(createdParameters).map((parameter) => parameter.parameterArn)
+        })
+      ]
+    })
+
+    new CfnOutput(this, "ReadParametersPolicyOutput", {
+      description: readPolicyOutputDescription,
+      value: readParametersPolicy.managedPolicyArn,
+      exportName: `${stackName}-${readPolicyExportSuffix}`
+    })
+
+    this.parameters = createdParameters
+    this.readParametersPolicy = readParametersPolicy
+  }
+}

packages/cdkConstructs/src/index.ts

@@ -7,6 +7,7 @@ export * from "./constructs/RestApiGateway/accessLogFormat.js"
 export * from "./constructs/RestApiGateway/LambdaEndpoint.js"
 export * from "./constructs/RestApiGateway/StateMachineEndpoint.js"
 export * from "./constructs/PythonLambdaFunction.js"
+export * from "./constructs/SsmParametersConstruct.js"
 export * from "./apps/createApp.js"
 export * from "./config/index.js"
 export * from "./utils/helpers.js"

packages/cdkConstructs/tests/config/index.test.ts

@@ -93,6 +93,12 @@ describe("config helpers", () => {
     expect(getConfigFromEnvVar("STACK_NAME")).toBe("primary")
   })
 
+  test("getConfigFromEnvVar returns the default value when env var is not set", () => {
+    delete process.env.CDK_CONFIG_MISSING
+
+    expect(getConfigFromEnvVar("MISSING", "CDK_CONFIG_", "fallback")).toBe("fallback")
+  })
+
   test("getConfigFromEnvVar throws when value is missing", () => {
     delete process.env.CDK_CONFIG_MISSING
 
@@ -114,12 +120,31 @@ describe("config helpers", () => {
     expect(getBooleanConfigFromEnvVar("OTHER_FLAG")).toBe(false)
   })
 
+  test("getBooleanConfigFromEnvVar uses default value when env var is not set", () => {
+    delete process.env.CDK_CONFIG_BOOL_MISSING
+
+    expect(getBooleanConfigFromEnvVar("BOOL_MISSING", "CDK_CONFIG_", "true")).toBe(true)
+    expect(getBooleanConfigFromEnvVar("BOOL_MISSING", "CDK_CONFIG_", "false")).toBe(false)
+  })
+
   test("getNumberConfigFromEnvVar parses numeric strings", () => {
     process.env.CDK_CONFIG_TIMEOUT = "45"
 
     expect(getNumberConfigFromEnvVar("TIMEOUT")).toBe(45)
   })
 
+  test("getNumberConfigFromEnvVar uses default value when env var is not set", () => {
+    delete process.env.CDK_CONFIG_NUM_MISSING
+
+    expect(getNumberConfigFromEnvVar("NUM_MISSING", "CDK_CONFIG_", "99")).toBe(99)
+  })
+
+  test("getConfigFromEnvVar ignores default value when env var is set", () => {
+    process.env.CDK_CONFIG_STACK_NAME = "primary"
+
+    expect(getConfigFromEnvVar("STACK_NAME", "CDK_CONFIG_", "ignored")).toBe("primary")
+  })
+
   test("getTrustStoreVersion returns the version ID from S3", async () => {
     mockCloudFormationSend.mockResolvedValueOnce({
       Stacks: [{