@friggframework/devtools 2.0.0-next.100 → 2.0.0-next.102

package/infrastructure/domains/networking/vpc-discovery.test.js

@@ -253,7 +253,7 @@ describe('VpcDiscovery', () => {
             expect(mockProvider.discoverVpc).toHaveBeenCalledWith(config);
         });
 
-        it('should discover all VPC endpoints (S3, DynamoDB, KMS, Secrets Manager)', async () => {
+        it('should discover all VPC endpoints (S3, DynamoDB, KMS, Secrets Manager, SQS, SSM)', async () => {
             mockProvider.discoverVpc.mockResolvedValue({
                 vpcId: 'vpc-123',
                 vpcCidr: '10.0.0.0/16',
@@ -283,6 +283,22 @@ describe('VpcDiscovery', () => {
                         ServiceName: 'com.amazonaws.us-east-1.secretsmanager',
                         State: 'available',
                     },
+                    {
+                        VpcEndpointId: 'vpce-sqs-def',
+                        ServiceName: 'com.amazonaws.us-east-1.sqs',
+                        State: 'available',
+                    },
+                    // ssmmessages must NOT be mistaken for the ssm endpoint
+                    {
+                        VpcEndpointId: 'vpce-ssmmessages-000',
+                        ServiceName: 'com.amazonaws.us-east-1.ssmmessages',
+                        State: 'available',
+                    },
+                    {
+                        VpcEndpointId: 'vpce-ssm-ghi',
+                        ServiceName: 'com.amazonaws.us-east-1.ssm',
+                        State: 'available',
+                    },
                 ],
             });
 
@@ -292,6 +308,8 @@ describe('VpcDiscovery', () => {
             expect(result.dynamodbVpcEndpointId).toBe('vpce-ddb-456');
             expect(result.kmsVpcEndpointId).toBe('vpce-kms-789');
             expect(result.secretsManagerVpcEndpointId).toBe('vpce-sm-abc');
+            expect(result.sqsVpcEndpointId).toBe('vpce-sqs-def');
+            expect(result.ssmVpcEndpointId).toBe('vpce-ssm-ghi');
         });
 
         it('should handle partial VPC endpoint discovery', async () => {

package/infrastructure/domains/networking/vpc-resolver.js

@@ -13,6 +13,7 @@
 
 const BaseResourceResolver = require('../shared/base-resolver');
 const { ResourceOwnership } = require('../shared/types');
+const { isSsmOffloadActive } = require('../parameters/offload-utils');
 
 class VpcResourceResolver extends BaseResourceResolver {
     /**
@@ -381,7 +382,8 @@ class VpcResourceResolver extends BaseResourceResolver {
                 dynamodb: { ownership: null, reason: 'VPC Endpoints disabled' },
                 kms: { ownership: null, reason: 'VPC Endpoints disabled' },
                 secretsManager: { ownership: null, reason: 'VPC Endpoints disabled' },
-                sqs: { ownership: null, reason: 'VPC Endpoints disabled' }
+                sqs: { ownership: null, reason: 'VPC Endpoints disabled' },
+                ssm: { ownership: null, reason: 'VPC Endpoints disabled' }
             };
         }
 
@@ -389,6 +391,9 @@ class VpcResourceResolver extends BaseResourceResolver {
         const encryptionMethod = appDefinition.encryption?.fieldLevelEncryptionMethod;
         const needsKms = encryptionMethod === 'kms';
 
+        // SSM endpoint only needed when parameter offload is active
+        const needsSsm = isSsmOffloadActive(appDefinition);
+
         // DynamoDB endpoint only needed if using DynamoDB (not MongoDB or PostgreSQL)
         // Currently framework only supports MongoDB (via Prisma) and PostgreSQL (via Aurora)
         // If not using DynamoDB, skip the endpoint (CloudFormation will delete if it exists)
@@ -403,7 +408,10 @@ class VpcResourceResolver extends BaseResourceResolver {
                 ? this._resolveEndpoint('FriggKMSVPCEndpoint', 'kms', userIntent, appDefinition, discovery)
                 : { ownership: null, reason: 'KMS endpoint not needed (encryption method is not KMS)' },
             secretsManager: this._resolveEndpoint('FriggSecretsManagerVPCEndpoint', 'secretsManager', userIntent, appDefinition, discovery),
-            sqs: this._resolveEndpoint('FriggSQSVPCEndpoint', 'sqs', userIntent, appDefinition, discovery)
+            sqs: this._resolveEndpoint('FriggSQSVPCEndpoint', 'sqs', userIntent, appDefinition, discovery),
+            ssm: needsSsm
+                ? this._resolveEndpoint('FriggSSMVPCEndpoint', 'ssm', userIntent, appDefinition, discovery)
+                : { ownership: null, reason: 'SSM endpoint not needed (SSM offload not active)' }
         };
 
         return endpoints;
@@ -421,7 +429,8 @@ class VpcResourceResolver extends BaseResourceResolver {
             'FriggDynamoDBVPCEndpoint': 'VPCEndpointDynamoDB',
             'FriggKMSVPCEndpoint': 'VPCEndpointKMS',
             'FriggSecretsManagerVPCEndpoint': 'VPCEndpointSecretsManager',
-            'FriggSQSVPCEndpoint': 'VPCEndpointSQS'
+            'FriggSQSVPCEndpoint': 'VPCEndpointSQS',
+            'FriggSSMVPCEndpoint': 'VPCEndpointSSM'
         };
         const oldLogicalId = oldLogicalIdMap[logicalId];
 

package/infrastructure/domains/networking/vpc-resolver.test.js

@@ -567,6 +567,46 @@ describe('VpcResourceResolver', () => {
             expect(decisions.kms.ownership).toBeNull();
             expect(decisions.secretsManager.ownership).toBeNull();
             expect(decisions.sqs.ownership).toBeNull();
+            expect(decisions.ssm.ownership).toBeNull();
+        });
+
+        describe('SSM endpoint', () => {
+            const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+            afterEach(() => {
+                if (originalSkipDiscovery === undefined) {
+                    delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+                } else {
+                    process.env.FRIGG_SKIP_AWS_DISCOVERY = originalSkipDiscovery;
+                }
+            });
+
+            it('should create SSM endpoint when offload is active', () => {
+                delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+                const appDefinition = {
+                    vpc: { ownership: { vpcEndpoints: 'auto' } },
+                    ssm: { enable: true },
+                    environment: { FOO: 'ssm' }
+                };
+                const discovery = { stackManaged: [], external: [], fromCloudFormation: false };
+
+                const decisions = resolver.resolveVpcEndpoints(appDefinition, discovery);
+
+                expect(decisions.ssm.ownership).toBe('stack');
+            });
+
+            it('should not create SSM endpoint when offload is not active', () => {
+                delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+                const appDefinition = {
+                    vpc: { ownership: { vpcEndpoints: 'auto' } },
+                    ssm: { enable: true }
+                };
+                const discovery = { stackManaged: [], external: [], fromCloudFormation: false };
+
+                const decisions = resolver.resolveVpcEndpoints(appDefinition, discovery);
+
+                expect(decisions.ssm.ownership).toBeNull();
+            });
         });
 
         it('should resolve to EXTERNAL with user-provided endpoint IDs', () => {

package/infrastructure/domains/parameters/offload-utils.js

@@ -0,0 +1,190 @@
+/**
+ * SSM Offload Utilities
+ *
+ * Shared helpers for the SSM Parameter Store offload feature. A variable is
+ * "offloaded" when its value lives in Parameter Store and is fetched by the
+ * runtime at cold start instead of being baked into the Lambda environment
+ * (which counts against the hard 4KB env-var limit).
+ *
+ * Consumed by the SsmBuilder, the environment builder, and the
+ * `frigg ssm push` CLI command so they all agree on the offload key set and
+ * parameter naming.
+ */
+
+const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+const DEFAULT_PARAMETER_PREFIX =
+    '/frigg/${self:service}/${self:provider.stage}';
+
+// INIT-phase preload shipped in @friggframework/core, present at this path in
+// every skipEsbuild handler (which packages the full node_modules tree).
+// LAMBDA_TASK_ROOT = /var/task.
+const SSM_PRELOAD_PATH =
+    '/var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
+
+// NODE_OPTIONS value that loads the INIT preload. Set ONLY on skipEsbuild
+// functions (esbuild-bundled functions do not package the .mjs, and a missing
+// --import target is a fatal Node startup error). No `${env:NODE_OPTIONS}`
+// prefix: that source resolves the deploy host's shell at package time, which
+// would leak an unrelated value into every Lambda.
+const SSM_PRELOAD_NODE_OPTIONS = `--import file://${SSM_PRELOAD_PATH}`;
+
+// Keys the framework itself sets (from discovered resources or the base
+// template) or that the loader/bypass handlers depend on before SSM values
+// are available. Never offloadable.
+const FRAMEWORK_ENV_BLOCKLIST = new Set([
+    'STAGE',
+    'FRIGG_STACK',
+    'FRIGG_STAGE',
+    'FRIGG_REGION',
+    'KMS_KEY_ARN',
+    'AES_KEY',
+    'AES_KEY_ID',
+    'DATABASE_URL',
+    'DATABASE_HOST',
+    'DATABASE_PORT',
+    'DATABASE_USER',
+    'DATABASE_PASSWORD',
+    'DATABASE_SECRET_ARN',
+    'DB_TYPE',
+    'MONGO_URI',
+    'SECRET_ARN',
+    'SSM_PARAMETER_PREFIX',
+    'FRIGG_SSM_OFFLOADED_KEYS',
+    'FRIGG_SSM_CACHE_TTL',
+    'WORKER_FUNCTION_NAME',
+    // Reserved AWS Lambda runtime variables
+    '_HANDLER',
+    '_X_AMZN_TRACE_ID',
+    'AWS_DEFAULT_REGION',
+    'AWS_EXECUTION_ENV',
+    'AWS_REGION',
+    'AWS_LAMBDA_FUNCTION_NAME',
+    'AWS_LAMBDA_FUNCTION_MEMORY_SIZE',
+    'AWS_LAMBDA_FUNCTION_VERSION',
+    'AWS_LAMBDA_INITIALIZATION_TYPE',
+    'AWS_LAMBDA_LOG_GROUP_NAME',
+    'AWS_LAMBDA_LOG_STREAM_NAME',
+    'AWS_ACCESS_KEY',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+]);
+
+/**
+ * Union of keys marked for SSM offload, sorted for deterministic output.
+ * Sources: appDefinition.environment values === 'ssm' and
+ * appDefinition.ssm.parameters keys. Does NOT filter invalid/blocklisted
+ * keys — use validateOffloadConfig() to surface those as errors instead of
+ * silently dropping them.
+ *
+ * @param {Object} appDefinition
+ * @returns {string[]}
+ */
+function getOffloadedKeys(appDefinition = {}) {
+    const keys = new Set();
+
+    for (const [key, value] of Object.entries(
+        appDefinition.environment || {}
+    )) {
+        if (value === 'ssm') keys.add(key);
+    }
+
+    for (const key of Object.keys(appDefinition.ssm?.parameters || {})) {
+        keys.add(key);
+    }
+
+    return [...keys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * Parameter path prefix under which offloaded values are stored. The default
+ * uses serverless variables resolved at package time and stays inside the
+ * *frigg* scope of the generated deployment IAM policies.
+ *
+ * @param {Object} appDefinition
+ * @returns {string}
+ */
+function getParameterPrefix(appDefinition = {}) {
+    const prefix =
+        appDefinition.ssm?.parameterPrefix || DEFAULT_PARAMETER_PREFIX;
+    return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+}
+
+/**
+ * Resolve the parameter prefix to a concrete path outside a serverless
+ * build (e.g. in the CLI), substituting the serverless variables the
+ * default prefix uses.
+ *
+ * @param {Object} appDefinition
+ * @param {string} stage
+ * @returns {string}
+ */
+function resolveParameterPrefix(appDefinition = {}, stage) {
+    return getParameterPrefix(appDefinition)
+        .replaceAll('${self:service}', appDefinition.name)
+        .replaceAll('${self:provider.stage}', stage);
+}
+
+/**
+ * Whether the offload feature is active for this build: SSM enabled, at
+ * least one key marked, and not running in local mode.
+ *
+ * @param {Object} appDefinition
+ * @returns {boolean}
+ */
+function isSsmOffloadActive(appDefinition = {}) {
+    if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') return false;
+    if (appDefinition.ssm?.enable !== true) return false;
+    return getOffloadedKeys(appDefinition).length > 0;
+}
+
+/**
+ * Validate the offload configuration. Returns errors (not warnings) for
+ * misconfigurations that would silently lose variables at runtime.
+ *
+ * @param {Object} appDefinition
+ * @returns {{errors: string[]}}
+ */
+function validateOffloadConfig(appDefinition = {}) {
+    const errors = [];
+    const offloadedKeys = getOffloadedKeys(appDefinition);
+
+    if (offloadedKeys.length === 0) {
+        return { errors };
+    }
+
+    if (appDefinition.ssm?.enable !== true) {
+        errors.push(
+            `Environment keys are marked for SSM offload (${offloadedKeys.join(
+                ', '
+            )}) but ssm.enable is not true. Set ssm: { enable: true } in the app definition.`
+        );
+    }
+
+    for (const key of offloadedKeys) {
+        if (FRAMEWORK_ENV_BLOCKLIST.has(key)) {
+            errors.push(
+                `${key} is a framework-managed environment variable and cannot be offloaded to SSM.`
+            );
+        } else if (!ENV_NAME_PATTERN.test(key)) {
+            errors.push(
+                `'${key}' is not a valid environment variable name (expected ${ENV_NAME_PATTERN}); it cannot be offloaded to SSM.`
+            );
+        }
+    }
+
+    return { errors };
+}
+
+module.exports = {
+    getOffloadedKeys,
+    getParameterPrefix,
+    resolveParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+    FRAMEWORK_ENV_BLOCKLIST,
+    DEFAULT_PARAMETER_PREFIX,
+    SSM_PRELOAD_PATH,
+    SSM_PRELOAD_NODE_OPTIONS,
+};

package/infrastructure/domains/parameters/offload-utils.test.js

@@ -0,0 +1,193 @@
+const {
+    getOffloadedKeys,
+    getParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+    FRAMEWORK_ENV_BLOCKLIST,
+} = require('./offload-utils');
+
+describe('offload-utils', () => {
+    const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+    afterEach(() => {
+        if (originalSkipDiscovery === undefined) {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+        } else {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = originalSkipDiscovery;
+        }
+    });
+
+    describe('getOffloadedKeys', () => {
+        it('returns empty array when nothing is marked', () => {
+            expect(getOffloadedKeys({})).toEqual([]);
+            expect(
+                getOffloadedKeys({ environment: { MY_VAR: true } })
+            ).toEqual([]);
+        });
+
+        it("collects environment keys marked 'ssm'", () => {
+            const keys = getOffloadedKeys({
+                environment: { B_VAR: 'ssm', A_VAR: 'ssm', PLAIN: true },
+            });
+            expect(keys).toEqual(['A_VAR', 'B_VAR']);
+        });
+
+        it('collects ssm.parameters keys', () => {
+            const keys = getOffloadedKeys({
+                ssm: {
+                    enable: true,
+                    parameters: { MY_SECRET: { type: 'SecureString' } },
+                },
+            });
+            expect(keys).toEqual(['MY_SECRET']);
+        });
+
+        it('unions and dedupes both sources, sorted', () => {
+            const keys = getOffloadedKeys({
+                environment: { SHARED: 'ssm', ENV_ONLY: 'ssm' },
+                ssm: {
+                    enable: true,
+                    parameters: {
+                        SHARED: { type: 'SecureString' },
+                        PARAM_ONLY: { type: 'String' },
+                    },
+                },
+            });
+            expect(keys).toEqual(['ENV_ONLY', 'PARAM_ONLY', 'SHARED']);
+        });
+    });
+
+    describe('getParameterPrefix', () => {
+        it('defaults to the frigg-scoped serverless-variable path', () => {
+            expect(getParameterPrefix({})).toBe(
+                '/frigg/${self:service}/${self:provider.stage}'
+            );
+        });
+
+        it('honors ssm.parameterPrefix override', () => {
+            expect(
+                getParameterPrefix({ ssm: { parameterPrefix: '/custom/x' } })
+            ).toBe('/custom/x');
+        });
+
+        it('strips a trailing slash from the override', () => {
+            expect(
+                getParameterPrefix({ ssm: { parameterPrefix: '/custom/x/' } })
+            ).toBe('/custom/x');
+        });
+    });
+
+    describe('resolveParameterPrefix', () => {
+        const { resolveParameterPrefix } = require('./offload-utils');
+
+        it('resolves the default prefix with service and stage', () => {
+            expect(
+                resolveParameterPrefix({ name: 'my-app' }, 'prod')
+            ).toBe('/frigg/my-app/prod');
+        });
+
+        it('resolves serverless tokens inside a custom prefix', () => {
+            expect(
+                resolveParameterPrefix(
+                    {
+                        name: 'my-app',
+                        ssm: {
+                            parameterPrefix:
+                                '/x/${self:service}/${self:provider.stage}',
+                        },
+                    },
+                    'dev'
+                )
+            ).toBe('/x/my-app/dev');
+        });
+
+        it('passes literal custom prefixes through', () => {
+            expect(
+                resolveParameterPrefix(
+                    { name: 'my-app', ssm: { parameterPrefix: '/plain/path' } },
+                    'dev'
+                )
+            ).toBe('/plain/path');
+        });
+    });
+
+    describe('isSsmOffloadActive', () => {
+        const offloadApp = {
+            ssm: { enable: true },
+            environment: { MY_SECRET: 'ssm' },
+        };
+
+        it('is true when ssm enabled and offload set non-empty', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(isSsmOffloadActive(offloadApp)).toBe(true);
+        });
+
+        it('is false without ssm.enable', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(
+                isSsmOffloadActive({ environment: { MY_SECRET: 'ssm' } })
+            ).toBe(false);
+        });
+
+        it('is false when nothing is offloaded', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(isSsmOffloadActive({ ssm: { enable: true } })).toBe(false);
+        });
+
+        it('is false in local mode (FRIGG_SKIP_AWS_DISCOVERY)', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            expect(isSsmOffloadActive(offloadApp)).toBe(false);
+        });
+    });
+
+    describe('validateOffloadConfig', () => {
+        it('passes for a clean offload config', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: { enable: true },
+                environment: { MY_SECRET: 'ssm' },
+            });
+            expect(errors).toEqual([]);
+        });
+
+        it('errors when offload markers exist without ssm.enable', () => {
+            const { errors } = validateOffloadConfig({
+                environment: { MY_SECRET: 'ssm' },
+            });
+            expect(errors.join(' ')).toMatch(/ssm\.enable/);
+        });
+
+        it('errors on framework-managed (blocklisted) keys', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: { enable: true },
+                environment: { DATABASE_URL: 'ssm' },
+            });
+            expect(errors.join(' ')).toMatch(/DATABASE_URL/);
+        });
+
+        it('errors on keys that are not valid env var names', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: {
+                    enable: true,
+                    parameters: { 'api-keys/foo': { type: 'String' } },
+                },
+            });
+            expect(errors.join(' ')).toMatch(/api-keys\/foo/);
+        });
+    });
+
+    it('blocklist covers the framework-managed keys', () => {
+        for (const key of [
+            'STAGE',
+            'FRIGG_STACK',
+            'KMS_KEY_ARN',
+            'DATABASE_URL',
+            'DATABASE_SECRET_ARN',
+            'SECRET_ARN',
+            'SSM_PARAMETER_PREFIX',
+            'FRIGG_SSM_OFFLOADED_KEYS',
+            'AWS_REGION',
+        ]) {
+            expect(FRAMEWORK_ENV_BLOCKLIST.has(key)).toBe(true);
+        }
+    });
+});

package/infrastructure/domains/parameters/ssm-builder.js

@@ -9,6 +9,12 @@
  */
 
 const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+const {
+    getOffloadedKeys,
+    getParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+} = require('./offload-utils');
 
 class SsmBuilder extends InfrastructureBuilder {
     constructor() {
@@ -41,6 +47,10 @@ class SsmBuilder extends InfrastructureBuilder {
             }
         }
 
+        for (const error of validateOffloadConfig(appDefinition).errors) {
+            result.addError(error);
+        }
+
         return result;
     }
 
@@ -55,20 +65,63 @@ class SsmBuilder extends InfrastructureBuilder {
             environment: {},
         };
 
-        // Add IAM permissions for SSM Parameter Store
-        result.iamStatements.push({
-            Effect: 'Allow',
-            Action: [
-                'ssm:GetParameter',
-                'ssm:GetParameters',
-                'ssm:GetParametersByPath',
-            ],
-            Resource: {
-                'Fn::Sub': 'arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/*',
-            },
-        });
-
-        console.log('  ✅ SSM Parameter Store IAM permissions added');
+        const ssmActions = [
+            'ssm:GetParameter',
+            'ssm:GetParameters',
+            'ssm:GetParametersByPath',
+        ];
+
+        const offloadActive = isSsmOffloadActive(appDefinition);
+
+        // Broad read grant, unless the app opts into prefix-only access while
+        // offload is active.
+        if (!(appDefinition.ssm.restrictIamToPrefix === true && offloadActive)) {
+            result.iamStatements.push({
+                Effect: 'Allow',
+                Action: ssmActions,
+                Resource: {
+                    'Fn::Sub': 'arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/*',
+                },
+            });
+            console.log('  ✅ SSM Parameter Store IAM permissions added');
+        }
+
+        if (offloadActive) {
+            const prefix = getParameterPrefix(appDefinition);
+            const offloadedKeys = getOffloadedKeys(appDefinition);
+
+            result.environment.SSM_PARAMETER_PREFIX = prefix;
+            result.environment.FRIGG_SSM_OFFLOADED_KEYS = offloadedKeys.join(',');
+
+            // The INIT-phase preload (NODE_OPTIONS=--import) that populates
+            // process.env before app modules load is set per-function on
+            // skipEsbuild handlers only — see infrastructure-composer.js. It
+            // cannot go here (provider.environment is global) because a missing
+            // --import target fatally aborts Node startup, and esbuild-bundled
+            // functions do not package the preload file.
+
+            // Prefix-scoped read grant. Built as a plain serverless string (not
+            // Fn::Sub) because the prefix contains serverless variables like
+            // ${self:service} that Fn::Sub would reject as bad substitution keys.
+            result.iamStatements.push({
+                Effect: 'Allow',
+                Action: ssmActions,
+                Resource: `arn:aws:ssm:\${self:provider.region}:\${aws:accountId}:parameter${prefix}/*`,
+            });
+            console.log(
+                `  ✅ SSM offload enabled for ${offloadedKeys.length} variable(s) under ${prefix}`
+            );
+
+            if (appDefinition.ssm.kmsKeyArn) {
+                result.iamStatements.push({
+                    Effect: 'Allow',
+                    Action: ['kms:Decrypt'],
+                    Resource: appDefinition.ssm.kmsKeyArn,
+                });
+                console.log('  ✅ KMS decrypt permission added for offloaded parameters');
+            }
+        }
+
         console.log(`[${this.name}] ✅ SSM configuration completed`);
 
         return result;