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

package/infrastructure/domains/scheduler/scheduler-builder.js

@@ -13,6 +13,11 @@
  */
 
 const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+const {
+    isScopedEnvironmentActive,
+    getIntegrationFunctionNames,
+    getAdminFunctionNames,
+} = require('../shared/function-environments');
 
 class SchedulerBuilder extends InfrastructureBuilder {
     constructor() {
@@ -70,7 +75,7 @@ class SchedulerBuilder extends InfrastructureBuilder {
         this.addSchedulerIamStatements(result);
 
         // Add environment variables
-        this.addEnvironmentVariables(result);
+        this.addEnvironmentVariables(result, appDefinition);
 
         console.log(`[${this.name}] ✅ Scheduler configuration completed`);
         return result;
@@ -196,15 +201,46 @@ class SchedulerBuilder extends InfrastructureBuilder {
     /**
      * Add environment variables for scheduler configuration
      */
-    addEnvironmentVariables(result) {
-        result.environment.SCHEDULER_ROLE_ARN = {
-            'Fn::GetAtt': ['SchedulerExecutionRole', 'Arn'],
-        };
-        result.environment.SCHEDULE_GROUP_NAME = {
-            Ref: 'FriggScheduleGroup',
+    addEnvironmentVariables(result, appDefinition = {}) {
+        const environment = {
+            SCHEDULER_ROLE_ARN: {
+                'Fn::GetAtt': ['SchedulerExecutionRole', 'Arn'],
+            },
+            SCHEDULE_GROUP_NAME: {
+                Ref: 'FriggScheduleGroup',
+            },
         };
 
-        console.log('  ✓ Added scheduler environment variables');
+        if (!isScopedEnvironmentActive(appDefinition)) {
+            Object.assign(result.environment, environment);
+            console.log('  ✓ Added scheduler environment variables');
+            return;
+        }
+
+        // Consumers: auth (runs integration actions), the executor (runs
+        // admin scripts that instantiate integrations), and every
+        // integration function. NOT adminScriptRouter — it carries its own
+        // admin-scheduler role, set directly by the admin-script builder.
+        const targets = [
+            'auth',
+            ...getAdminFunctionNames(appDefinition).filter(
+                (fnName) => fnName !== 'adminScriptRouter'
+            ),
+            ...(appDefinition.integrations || []).flatMap(
+                getIntegrationFunctionNames
+            ),
+        ];
+
+        result.functionEnvironments = result.functionEnvironments || {};
+        for (const fnName of targets) {
+            result.functionEnvironments[fnName] = {
+                ...result.functionEnvironments[fnName],
+                ...environment,
+            };
+        }
+        console.log(
+            `  ✓ Scoped scheduler environment variables to: ${targets.join(', ')}`
+        );
     }
 }
 

package/infrastructure/domains/scheduler/scheduler-builder.test.js

@@ -0,0 +1,118 @@
+/**
+ * Tests for Scheduler Builder
+ */
+
+const { SchedulerBuilder } = require('./scheduler-builder');
+
+describe('SchedulerBuilder', () => {
+    let schedulerBuilder;
+    const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+    beforeEach(() => {
+        schedulerBuilder = new SchedulerBuilder();
+        delete 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('shouldExecute()', () => {
+        it('runs when explicitly enabled', () => {
+            expect(
+                schedulerBuilder.shouldExecute({ scheduler: { enable: true } })
+            ).toBe(true);
+        });
+
+        it('runs when any integration has webhooks', () => {
+            expect(
+                schedulerBuilder.shouldExecute({
+                    integrations: [
+                        { Definition: { name: 'a', webhooks: true } },
+                    ],
+                })
+            ).toBe(true);
+        });
+
+        it('skips otherwise', () => {
+            expect(
+                schedulerBuilder.shouldExecute({
+                    integrations: [{ Definition: { name: 'a' } }],
+                })
+            ).toBe(false);
+        });
+    });
+
+    describe('build() environment', () => {
+        const scheduledApp = (extra = {}) => ({
+            scheduler: { enable: true },
+            integrations: [
+                { Definition: { name: 'hubspot', webhooks: true } },
+                { Definition: { name: 'slack' } },
+            ],
+            ...extra,
+        });
+
+        it('broadcasts scheduler vars app-wide by default', async () => {
+            const result = await schedulerBuilder.build(scheduledApp(), {});
+
+            expect(result.environment.SCHEDULER_ROLE_ARN).toEqual({
+                'Fn::GetAtt': ['SchedulerExecutionRole', 'Arn'],
+            });
+            expect(result.environment.SCHEDULE_GROUP_NAME).toEqual({
+                Ref: 'FriggScheduleGroup',
+            });
+            expect(result.functionEnvironments).toBeUndefined();
+        });
+
+        it('scopes scheduler vars to auth, adminScriptExecutor, and integration functions with lambda.scopedEnvironment', async () => {
+            const result = await schedulerBuilder.build(
+                scheduledApp({
+                    lambda: { scopedEnvironment: true },
+                    adminScripts: [{ Definition: { name: 'fix-things' } }],
+                }),
+                {}
+            );
+
+            expect(result.environment.SCHEDULER_ROLE_ARN).toBeUndefined();
+            expect(result.environment.SCHEDULE_GROUP_NAME).toBeUndefined();
+
+            const scoped = result.functionEnvironments;
+            for (const fnName of [
+                'auth',
+                'adminScriptExecutor',
+                'hubspot',
+                'hubspotWebhook',
+                'hubspotQueueWorker',
+                'slack',
+                'slackQueueWorker',
+            ]) {
+                expect(scoped[fnName].SCHEDULER_ROLE_ARN).toEqual({
+                    'Fn::GetAtt': ['SchedulerExecutionRole', 'Arn'],
+                });
+                expect(scoped[fnName].SCHEDULE_GROUP_NAME).toEqual({
+                    Ref: 'FriggScheduleGroup',
+                });
+            }
+
+            // the router keeps its own admin-scheduler role, set directly by
+            // the admin-script builder — never targeted here
+            expect(scoped.adminScriptRouter).toBeUndefined();
+        });
+
+        it('keeps broadcasting in local mode even with the flag on', async () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const result = await schedulerBuilder.build(
+                scheduledApp({ lambda: { scopedEnvironment: true } }),
+                {}
+            );
+
+            expect(result.environment.SCHEDULER_ROLE_ARN).toBeDefined();
+            expect(result.functionEnvironments).toBeUndefined();
+        });
+    });
+});

package/infrastructure/domains/security/iam-generator.js

@@ -7,6 +7,7 @@ const path = require('path');
  * @param {Object} [options.features={}] - Enabled features { vpc, kms, ssm, websockets }
  * @param {string} [options.userPrefix='frigg-deployment-user'] - IAM user name prefix
  * @param {string} [options.stackName='frigg-deployment-iam'] - CloudFormation stack name
+ * @param {string} [options.ssmKmsKeyArn] - Customer-managed KMS key ARN for SecureString offload (appDefinition.ssm.kmsKeyArn)
  * @returns {string} CloudFormation YAML template
  */
 function generateIAMCloudFormation(options = {}) {
@@ -14,7 +15,8 @@ function generateIAMCloudFormation(options = {}) {
         appName = 'Frigg',
         features = {},
         userPrefix = 'frigg-deployment-user',
-        stackName = 'frigg-deployment-iam'
+        stackName = 'frigg-deployment-iam',
+        ssmKmsKeyArn
     } = options;
 
     const deploymentUserName = userPrefix;
@@ -667,6 +669,9 @@ function generateIAMCloudFormation(options = {}) {
                                 'ssm:GetParameter',
                                 'ssm:GetParameters',
                                 'ssm:GetParametersByPath',
+                                'ssm:PutParameter',
+                                'ssm:DeleteParameter',
+                                'ssm:AddTagsToResource',
                             ],
                             Resource: [
                                 {
@@ -679,6 +684,32 @@ function generateIAMCloudFormation(options = {}) {
                                 },
                             ],
                         },
+                        {
+                            // SecureString offload: SSM performs the KMS encrypt/decrypt
+                            // on the caller's behalf, so the grant is scoped to ViaService ssm.*
+                            Sid: 'FriggSSMParameterKMSEncryption',
+                            Effect: 'Allow',
+                            Action: [
+                                'kms:Encrypt',
+                                'kms:GenerateDataKey',
+                                'kms:Decrypt',
+                            ],
+                            Resource: ssmKmsKeyArn
+                                ? [ssmKmsKeyArn]
+                                : [
+                                      {
+                                          'Fn::Sub':
+                                              'arn:aws:kms:*:${AWS::AccountId}:key/*',
+                                      },
+                                  ],
+                            Condition: {
+                                StringEquals: {
+                                    'kms:ViaService': [
+                                        'ssm.*.amazonaws.com',
+                                    ],
+                                },
+                            },
+                        },
                     ],
                 },
             },
@@ -773,6 +804,7 @@ function getFeatureSummary(appDefinition) {
         features,
         integrationCount,
         appName: appDefinition.name || 'Unnamed Frigg App',
+        ssmKmsKeyArn: appDefinition.ssm?.kmsKeyArn,
     };
 }
 

package/infrastructure/domains/security/iam-generator.test.js

@@ -38,6 +38,34 @@ describe('IAM Generator', () => {
             expect(summary.features.ssm).toBe(false);
             expect(summary.features.websockets).toBe(false);
         });
+
+        it('should surface ssm.kmsKeyArn from the app definition', () => {
+            const appDefinition = {
+                name: 'test-app',
+                ssm: {
+                    enable: true,
+                    kmsKeyArn:
+                        'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+                }
+            };
+
+            const summary = getFeatureSummary(appDefinition);
+
+            expect(summary.ssmKmsKeyArn).toBe(
+                'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+            );
+        });
+
+        it('should leave ssmKmsKeyArn undefined when not configured', () => {
+            const appDefinition = {
+                name: 'test-app',
+                ssm: { enable: true }
+            };
+
+            const summary = getFeatureSummary(appDefinition);
+
+            expect(summary.ssmKmsKeyArn).toBeUndefined();
+        });
     });
 
     describe('generateIAMCloudFormation', () => {
@@ -120,6 +148,51 @@ describe('IAM Generator', () => {
             expect(yaml).toContain('EnableSSMSupport');
         });
 
+        it('should grant SSM-mediated KMS access via ssm.*.amazonaws.com when SSM is enabled', () => {
+            const appDefinition = {
+                name: 'test-app',
+                integrations: [],
+                ssm: { enable: true }
+            };
+
+            const summary = getFeatureSummary(appDefinition);
+            const yaml = generateIAMCloudFormation({
+                appName: summary.appName,
+                features: summary.features
+            });
+
+            expect(yaml).toContain('FriggSSMParameterKMSEncryption');
+            expect(yaml).toContain('kms:Encrypt');
+            expect(yaml).toContain('ssm.*.amazonaws.com');
+            // No customer-managed key configured: falls back to the account key wildcard
+            expect(yaml).toContain('arn:aws:kms:*:${AWS::AccountId}:key/*');
+        });
+
+        it('should scope the SSM KMS grant to ssm.kmsKeyArn when provided', () => {
+            const appDefinition = {
+                name: 'test-app',
+                integrations: [],
+                ssm: {
+                    enable: true,
+                    kmsKeyArn:
+                        'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+                }
+            };
+
+            const summary = getFeatureSummary(appDefinition);
+            const yaml = generateIAMCloudFormation({
+                appName: summary.appName,
+                features: summary.features,
+                ssmKmsKeyArn: appDefinition.ssm.kmsKeyArn
+            });
+
+            expect(yaml).toContain('FriggSSMParameterKMSEncryption');
+            expect(yaml).toContain(
+                'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+            );
+            expect(yaml).not.toContain('arn:aws:kms:*:${AWS::AccountId}:key/*');
+        });
+
         it('should set correct default parameter values based on features', () => {
             const appDefinition = {
                 name: 'test-app',

package/infrastructure/domains/security/templates/frigg-deployment-iam-stack.yaml

@@ -360,9 +360,24 @@ Resources:
               - 'ssm:GetParameter'
               - 'ssm:GetParameters'
               - 'ssm:GetParametersByPath'
+              - 'ssm:PutParameter'
+              - 'ssm:DeleteParameter'
+              - 'ssm:AddTagsToResource'
             Resource:
               - !Sub 'arn:aws:ssm:*:${AWS::AccountId}:parameter/*frigg*'
               - !Sub 'arn:aws:ssm:*:${AWS::AccountId}:parameter/*frigg*/*'
+          - Sid: 'FriggSSMParameterKMSEncryption'
+            Effect: Allow
+            Action:
+              - 'kms:Encrypt'
+              - 'kms:GenerateDataKey'
+              - 'kms:Decrypt'
+            Resource:
+              - !Sub 'arn:aws:kms:*:${AWS::AccountId}:key/*'
+            Condition:
+              StringEquals:
+                'kms:ViaService':
+                  - 'ssm.*.amazonaws.com'
 
   # Store access key in Secrets Manager
   FriggDeploymentCredentials:

package/infrastructure/domains/security/templates/iam-policy-full.json

@@ -256,6 +256,7 @@
       "Sid": "FriggKMSEncryptionPermissions",
       "Effect": "Allow",
       "Action": [
+        "kms:Encrypt",
         "kms:GenerateDataKey",
         "kms:Decrypt"
       ],
@@ -266,7 +267,8 @@
         "StringEquals": {
           "kms:ViaService": [
             "lambda.*.amazonaws.com",
-            "s3.*.amazonaws.com"
+            "s3.*.amazonaws.com",
+            "ssm.*.amazonaws.com"
           ]
         }
       }
@@ -277,7 +279,10 @@
       "Action": [
         "ssm:GetParameter",
         "ssm:GetParameters",
-        "ssm:GetParametersByPath"
+        "ssm:GetParametersByPath",
+        "ssm:PutParameter",
+        "ssm:DeleteParameter",
+        "ssm:AddTagsToResource"
       ],
       "Resource": [
         "arn:aws:ssm:*:*:parameter/*frigg*",

package/infrastructure/domains/shared/builder-orchestrator.js

@@ -144,6 +144,7 @@ class BuilderOrchestrator {
             iamStatements: [],
             environment: {},
             functions: {},
+            functionEnvironments: {},
             layers: {},
             plugins: [],
             custom: {},
@@ -172,6 +173,19 @@ class BuilderOrchestrator {
                 Object.assign(merged.functions, result.functions);
             }
 
+            // Merge function-scoped environment maps (applied by the
+            // composer once base + builder functions all exist)
+            if (result.functionEnvironments) {
+                for (const [fnName, env] of Object.entries(
+                    result.functionEnvironments
+                )) {
+                    merged.functionEnvironments[fnName] = {
+                        ...merged.functionEnvironments[fnName],
+                        ...env,
+                    };
+                }
+            }
+
             // Merge layers
             if (result.layers) {
                 Object.assign(merged.layers, result.layers);

package/infrastructure/domains/shared/builder-orchestrator.test.js

@@ -208,6 +208,51 @@ describe('BuilderOrchestrator', () => {
 
             await expect(orchestrator.buildAll({})).rejects.toThrow('Build failed');
         });
+
+        it('should merge functionEnvironments per function, later builder winning on key conflict', async () => {
+            class ScopedEnvBuilderA extends InfrastructureBuilder {
+                getName() { return 'ScopedEnvBuilderA'; }
+                shouldExecute() { return true; }
+                validate() { return new ValidationResult(); }
+                async build() {
+                    return {
+                        functionEnvironments: {
+                            auth: { QUEUE_A: 'url-a', SHARED: 'from-a' },
+                            workerA: { QUEUE_A: 'url-a' },
+                        },
+                    };
+                }
+            }
+            class ScopedEnvBuilderB extends InfrastructureBuilder {
+                getName() { return 'ScopedEnvBuilderB'; }
+                shouldExecute() { return true; }
+                validate() { return new ValidationResult(); }
+                getDependencies() { return ['ScopedEnvBuilderA']; }
+                async build() {
+                    return {
+                        functionEnvironments: {
+                            auth: { QUEUE_B: 'url-b', SHARED: 'from-b' },
+                        },
+                    };
+                }
+            }
+
+            orchestrator = new BuilderOrchestrator([
+                new ScopedEnvBuilderA(),
+                new ScopedEnvBuilderB(),
+            ]);
+
+            const result = await orchestrator.buildAll({});
+
+            expect(result.merged.functionEnvironments).toEqual({
+                auth: {
+                    QUEUE_A: 'url-a',
+                    QUEUE_B: 'url-b',
+                    SHARED: 'from-b',
+                },
+                workerA: { QUEUE_A: 'url-a' },
+            });
+        });
     });
 });
 

package/infrastructure/domains/shared/environment-builder.js

@@ -9,12 +9,19 @@
  * 3. Generated resource references
  */
 
+const { isSsmOffloadActive, getOffloadedKeys } = require('../parameters/offload-utils');
+
 /**
  * Get environment variables from AppDefinition
- * 
+ *
  * Extracts environment variable definitions where value is true,
  * and creates Serverless variable references.
- * 
+ *
+ * A value of 'ssm' offloads the variable to Parameter Store when offload is
+ * active (see SsmBuilder), keeping it out of the Lambda env map. When offload
+ * is not active (local mode / ssm disabled) it falls back to the same
+ * `${env:KEY, ''}` reference as `true` so `frigg start` + dotenv keeps working.
+ *
  * @param {Object} appDefinition - Application definition
  * @returns {Object} Environment variable mappings
  */
@@ -38,16 +45,38 @@ function getAppEnvironmentVars(appDefinition) {
         'AWS_SESSION_TOKEN',
     ]);
 
-    if (!appDefinition.environment) {
-        return envVars;
-    }
+    const environment = appDefinition.environment || {};
 
     console.log('📋 Loading environment variables from appDefinition...');
     const envKeys = [];
     const skippedKeys = [];
+    const offloadedKeys = [];
+    const offloadActive = isSsmOffloadActive(appDefinition);
 
-    for (const [key, value] of Object.entries(appDefinition.environment)) {
-        if (value !== true) continue;
+    for (const [key, value] of Object.entries(environment)) {
+        if (value === 'ssm' && offloadActive) {
+            offloadedKeys.push(key);
+            continue;
+        }
+        if (value !== true && value !== 'ssm') continue;
+        if (reservedVars.has(key)) {
+            skippedKeys.push(key);
+            continue;
+        }
+        envVars[key] = `\${env:${key}, ''}`;
+        envKeys.push(key);
+    }
+
+    // Keys declared only in ssm.parameters (no matching `environment` entry)
+    // get the same local-fallback treatment as `environment`-valued 'ssm' keys.
+    const ssmOnlyKeys = getOffloadedKeys(appDefinition).filter(
+        (key) => !(key in environment)
+    );
+    for (const key of ssmOnlyKeys) {
+        if (offloadActive) {
+            offloadedKeys.push(key);
+            continue;
+        }
         if (reservedVars.has(key)) {
             skippedKeys.push(key);
             continue;
@@ -69,6 +98,13 @@ function getAppEnvironmentVars(appDefinition) {
             } reserved AWS Lambda variables: ${skippedKeys.join(', ')}`
         );
     }
+    if (offloadedKeys.length > 0) {
+        console.log(
+            `   🔒 Offloaded ${offloadedKeys.length} variables to SSM: ${offloadedKeys.join(
+                ', '
+            )}`
+        );
+    }
 
     return envVars;
 }

package/infrastructure/domains/shared/environment-builder.test.js

@@ -38,7 +38,7 @@ describe('Environment Builder', () => {
             expect(result.DISABLED_VAR).toBeUndefined();
         });
 
-        it('should ignore environment variables with non-boolean values', () => {
+        it("ignores non-boolean values other than the meaningful 'ssm' marker", () => {
             const appDefinition = {
                 environment: {
                     VALID: true,
@@ -108,6 +108,102 @@ describe('Environment Builder', () => {
         });
     });
 
+    describe("getAppEnvironmentVars() - 'ssm' offload", () => {
+        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("excludes 'ssm' keys when offload is active", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm', BAR: true },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBeUndefined();
+            expect(result.BAR).toBe("${env:BAR, ''}");
+        });
+
+        it("falls back to env reference for 'ssm' keys when FRIGG_SKIP_AWS_DISCOVERY is set", () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBe("${env:FOO, ''}");
+        });
+
+        it("falls back to env reference for 'ssm' keys when ssm is disabled", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: false },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBe("${env:FOO, ''}");
+        });
+
+        it('falls back to env reference for a key declared only in ssm.parameters when FRIGG_SKIP_AWS_DISCOVERY is set', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.HUBSPOT_CLIENT_SECRET).toBe("${env:HUBSPOT_CLIENT_SECRET, ''}");
+        });
+
+        it('excludes a key declared only in ssm.parameters when offload is active', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.HUBSPOT_CLIENT_SECRET).toBeUndefined();
+        });
+
+        it("does not double-process a key present in both environment:'ssm' and ssm.parameters", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { FOO: { type: 'SecureString' } },
+                },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBeUndefined();
+
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const fallbackResult = getAppEnvironmentVars(appDefinition);
+            expect(fallbackResult.FOO).toBe("${env:FOO, ''}");
+        });
+    });
+
     describe('buildEnvironment()', () => {
         it('should combine app vars with standard Frigg variables', () => {
             const appEnvironmentVars = {