@friggframework/devtools 2.0.0--canary.623.b39b42d.0 → 2.0.0--canary.625.950ba82.0

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

@@ -0,0 +1,175 @@
+/**
+ * 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}';
+
+// 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();
+}
+
+/**
+ * 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,
+};

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,56 @@ 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(',');
+
+            // 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;

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

@@ -72,7 +72,7 @@ describe('SsmBuilder', () => {
                 ssm: {
                     enable: true,
                     parameters: {
-                        DATABASE_URL: '/my-app/database-url',
+                        SERVICE_TOKEN: '/my-app/service-token',
                         API_KEY: '/my-app/api-key',
                     },
                 },
@@ -119,6 +119,42 @@ describe('SsmBuilder', () => {
             expect(result.valid).toBe(false);
             expect(result.errors.some(e => e.includes('ssm.parameters must be an object'))).toBe(true);
         });
+
+        it('should error when keys are marked for offload but ssm.enable is not true', () => {
+            const appDefinition = {
+                ssm: { enable: false },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = ssmBuilder.validate(appDefinition);
+
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes('ssm.enable is not true'))).toBe(true);
+        });
+
+        it('should error when a blocklisted key is marked for offload', () => {
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { DATABASE_URL: 'ssm' },
+            };
+
+            const result = ssmBuilder.validate(appDefinition);
+
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes('DATABASE_URL'))).toBe(true);
+        });
+
+        it('should error when an invalid env name is marked for offload', () => {
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { 'bad-name': 'ssm' },
+            };
+
+            const result = ssmBuilder.validate(appDefinition);
+
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes('bad-name'))).toBe(true);
+        });
     });
 
     describe('build()', () => {
@@ -170,6 +206,114 @@ describe('SsmBuilder', () => {
 
             expect(result1.iamStatements).toEqual(result2.iamStatements);
         });
+
+        it('should return empty environment when no keys are offloaded', async () => {
+            const appDefinition = {
+                ssm: { enable: true },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            expect(result.environment).toEqual({});
+            expect(result.iamStatements).toHaveLength(1);
+        });
+    });
+
+    describe('build() - offload active', () => {
+        it('should add prefix and offloaded keys env vars', async () => {
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm', BAR: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            expect(result.environment.SSM_PARAMETER_PREFIX).toBe(
+                '/frigg/${self:service}/${self:provider.stage}'
+            );
+            expect(result.environment.FRIGG_SSM_OFFLOADED_KEYS).toBe('BAR,FOO');
+        });
+
+        it('should add a prefix-scoped read statement while retaining the broad grant by default', async () => {
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            const broad = result.iamStatements.find(
+                s => s.Resource && s.Resource['Fn::Sub'] === 'arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/*'
+            );
+            expect(broad).toBeDefined();
+
+            const scoped = result.iamStatements.find(
+                s => s.Resource === 'arn:aws:ssm:${self:provider.region}:${aws:accountId}:parameter/frigg/${self:service}/${self:provider.stage}/*'
+            );
+            expect(scoped).toBeDefined();
+            expect(scoped.Action).toEqual([
+                'ssm:GetParameter',
+                'ssm:GetParameters',
+                'ssm:GetParametersByPath',
+            ]);
+        });
+
+        it('should drop the broad grant when restrictIamToPrefix is set', async () => {
+            const appDefinition = {
+                ssm: { enable: true, restrictIamToPrefix: true },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            const broad = result.iamStatements.find(
+                s => s.Resource && s.Resource['Fn::Sub']
+            );
+            expect(broad).toBeUndefined();
+
+            const scoped = result.iamStatements.find(
+                s => s.Resource === 'arn:aws:ssm:${self:provider.region}:${aws:accountId}:parameter/frigg/${self:service}/${self:provider.stage}/*'
+            );
+            expect(scoped).toBeDefined();
+        });
+
+        it('should add kms:Decrypt when kmsKeyArn is set', async () => {
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    kmsKeyArn: 'arn:aws:kms:us-east-1:123456789012:key/abc-123',
+                },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            const decrypt = result.iamStatements.find(
+                s => Array.isArray(s.Action) && s.Action.includes('kms:Decrypt')
+            );
+            expect(decrypt).toEqual({
+                Effect: 'Allow',
+                Action: ['kms:Decrypt'],
+                Resource: 'arn:aws:kms:us-east-1:123456789012:key/abc-123',
+            });
+        });
+
+        it('should honor a custom parameterPrefix', async () => {
+            const appDefinition = {
+                ssm: { enable: true, parameterPrefix: '/custom/${self:provider.stage}' },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            expect(result.environment.SSM_PARAMETER_PREFIX).toBe(
+                '/custom/${self:provider.stage}'
+            );
+            const scoped = result.iamStatements.find(
+                s => s.Resource === 'arn:aws:ssm:${self:provider.region}:${aws:accountId}:parameter/custom/${self:provider.stage}/*'
+            );
+            expect(scoped).toBeDefined();
+        });
     });
 
     describe('getDependencies()', () => {