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

package/infrastructure/domains/shared/function-environments.js

@@ -0,0 +1,97 @@
+/**
+ * Per-function environment scoping (ADR-027)
+ *
+ * Builders emit `result.functionEnvironments` — a map of function name to
+ * env vars — instead of broadcasting framework vars app-wide through
+ * `result.environment`. The composer applies the merged map onto the final
+ * function definitions after every function (base + builder) exists.
+ */
+
+/**
+ * Whether builders should scope framework env vars per function. Skipped in
+ * local mode: the serverless-plugin injects LocalStack queue URLs at
+ * provider level only, and function-level values would shadow them.
+ *
+ * @param {Object} appDefinition
+ * @returns {boolean}
+ */
+function isScopedEnvironmentActive(appDefinition = {}) {
+    if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') return false;
+    return appDefinition.lambda?.scopedEnvironment === true;
+}
+
+/**
+ * Apply a merged functionEnvironments map onto the composed functions.
+ * A key a builder already set directly on a function wins (e.g. the
+ * admin-script router's own SCHEDULER_ROLE_ARN must not be clobbered by
+ * the integration-scheduler value). An unknown function name is a hard
+ * error — silently dropping a var would surface as a runtime failure.
+ *
+ * @param {Object} functions - definition.functions (mutated)
+ * @param {Object} functionEnvironments - { fnName: { KEY: value } }
+ */
+function applyFunctionEnvironments(functions, functionEnvironments = {}) {
+    for (const [fnName, env] of Object.entries(functionEnvironments)) {
+        const fn = functions[fnName];
+        if (!fn) {
+            throw new Error(
+                `functionEnvironments targets unknown function '${fnName}' (known: ${Object.keys(
+                    functions
+                ).join(', ')})`
+            );
+        }
+        fn.environment = { ...env, ...(fn.environment || {}) };
+    }
+}
+
+/**
+ * Function names the integration builder creates for one integration.
+ * Wire contract: must stay in sync with
+ * IntegrationBuilder.createFunctionDefinitions — a drift here surfaces as a
+ * hard unknown-function error at compose time, not a silent var drop.
+ *
+ * @param {Object} integration - entry from appDefinition.integrations
+ * @returns {string[]}
+ */
+function getIntegrationFunctionNames(integration) {
+    const name = integration.Definition.name;
+    const names = [name, `${name}QueueWorker`];
+
+    const webhooks = integration.Definition.webhooks;
+    if (webhooks === true || webhooks?.enabled === true) {
+        names.splice(1, 0, `${name}Webhook`);
+    }
+
+    for (const [bindingKey, binding] of Object.entries(
+        integration.Definition.extensions || {}
+    )) {
+        const routes = binding?.extension?.routes || [];
+        if (routes.length === 0) continue;
+        names.push(`${name}__${String(bindingKey).replace(/[^A-Za-z0-9]/g, '')}`);
+    }
+
+    return names;
+}
+
+/**
+ * Admin-script functions, when the feature is on (mirrors
+ * AdminScriptBuilder.shouldExecute). Both can instantiate arbitrary
+ * integrations, so they belong in every integration's queue-URL consumer
+ * set.
+ *
+ * @param {Object} appDefinition
+ * @returns {string[]}
+ */
+function getAdminFunctionNames(appDefinition = {}) {
+    return Array.isArray(appDefinition.adminScripts) &&
+        appDefinition.adminScripts.length > 0
+        ? ['adminScriptRouter', 'adminScriptExecutor']
+        : [];
+}
+
+module.exports = {
+    isScopedEnvironmentActive,
+    applyFunctionEnvironments,
+    getIntegrationFunctionNames,
+    getAdminFunctionNames,
+};

package/infrastructure/domains/shared/function-environments.test.js

@@ -0,0 +1,146 @@
+const {
+    isScopedEnvironmentActive,
+    applyFunctionEnvironments,
+} = require('./function-environments');
+
+describe('function-environments', () => {
+    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('isScopedEnvironmentActive', () => {
+        it('is true only when lambda.scopedEnvironment is set', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: true },
+                })
+            ).toBe(true);
+            expect(isScopedEnvironmentActive({})).toBe(false);
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: false },
+                })
+            ).toBe(false);
+        });
+
+        it('is false in local mode: the serverless-plugin injects LocalStack queue URLs at provider level only', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: true },
+                })
+            ).toBe(false);
+        });
+    });
+
+    describe('getIntegrationFunctionNames', () => {
+        const { getIntegrationFunctionNames } = require('./function-environments');
+
+        it('always includes the router and queue worker', () => {
+            expect(
+                getIntegrationFunctionNames({ Definition: { name: 'hubspot' } })
+            ).toEqual(['hubspot', 'hubspotQueueWorker']);
+        });
+
+        it('includes the webhook handler when webhooks are enabled', () => {
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: true },
+                })
+            ).toContain('hubspotWebhook');
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: { enabled: true } },
+                })
+            ).toContain('hubspotWebhook');
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: { enabled: false } },
+                })
+            ).not.toContain('hubspotWebhook');
+        });
+
+        it('includes one function per routed extension binding, sanitized', () => {
+            const names = getIntegrationFunctionNames({
+                Definition: {
+                    name: 'hubspot',
+                    extensions: {
+                        'my-ext': { extension: { routes: [{ path: '/x', method: 'GET' }] } },
+                        routeless: { extension: { routes: [] } },
+                    },
+                },
+            });
+            expect(names).toContain('hubspot__myext');
+            expect(names).not.toContain('hubspot__routeless');
+        });
+    });
+
+    describe('getAdminFunctionNames', () => {
+        const { getAdminFunctionNames } = require('./function-environments');
+
+        it('returns the admin functions only when admin scripts are configured', () => {
+            expect(
+                getAdminFunctionNames({ adminScripts: [{ Definition: { name: 'x' } }] })
+            ).toEqual(['adminScriptRouter', 'adminScriptExecutor']);
+            expect(getAdminFunctionNames({})).toEqual([]);
+            expect(getAdminFunctionNames({ adminScripts: [] })).toEqual([]);
+        });
+    });
+
+    describe('applyFunctionEnvironments', () => {
+        const makeFunctions = () => ({
+            auth: { handler: 'auth.handler' },
+            hubspot: {
+                handler: 'hubspot.handler',
+                environment: { EXISTING: 'builder-set' },
+            },
+        });
+
+        it('assigns scoped env vars onto the target functions', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {
+                auth: { HUBSPOT_QUEUE_URL: 'url-1' },
+                hubspot: { HUBSPOT_QUEUE_URL: 'url-1' },
+            });
+
+            expect(functions.auth.environment).toEqual({
+                HUBSPOT_QUEUE_URL: 'url-1',
+            });
+            expect(functions.hubspot.environment).toEqual({
+                EXISTING: 'builder-set',
+                HUBSPOT_QUEUE_URL: 'url-1',
+            });
+        });
+
+        it('never clobbers a key a builder already set directly on the function', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {
+                hubspot: { EXISTING: 'scoped-value', OTHER: 'x' },
+            });
+
+            expect(functions.hubspot.environment.EXISTING).toBe('builder-set');
+            expect(functions.hubspot.environment.OTHER).toBe('x');
+        });
+
+        it('throws on an unknown function name instead of silently dropping vars', () => {
+            expect(() =>
+                applyFunctionEnvironments(makeFunctions(), {
+                    typoFunction: { A: '1' },
+                })
+            ).toThrow(/typoFunction/);
+        });
+
+        it('is a no-op for an empty map', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {});
+            expect(functions.auth.environment).toBeUndefined();
+        });
+    });
+});

package/infrastructure/infrastructure-composer.js

@@ -20,6 +20,7 @@ const { SchedulerBuilder } = require('./domains/scheduler/scheduler-builder');
 const { AdminScriptBuilder } = require('./domains/admin-scripts/admin-script-builder');
 
 // Utilities
+const { applyFunctionEnvironments } = require('./domains/shared/function-environments');
 const { modifyHandlerPaths } = require('./domains/shared/utilities/handler-path-resolver');
 const { createBaseDefinition } = require('./domains/shared/utilities/base-definition-factory');
 const { ensurePrismaLayerExists } = require('./domains/shared/utilities/prisma-layer-manager');
@@ -75,6 +76,10 @@ const composeServerlessDefinition = async (AppDefinition) => {
     definition.provider.iamRoleStatements.push(...merged.iamStatements);
     Object.assign(definition.provider.environment, merged.environment);
     Object.assign(definition.functions, merged.functions);
+    applyFunctionEnvironments(
+        definition.functions,
+        merged.functionEnvironments
+    );
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;

package/infrastructure/infrastructure-composer.test.js

@@ -1062,7 +1062,18 @@ describe('composeServerlessDefinition', () => {
     });
 
     describe('SSM Configuration', () => {
-        it('should add SSM configuration when ssm.enable is true', async () => {
+        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 add the broad SSM read grant when ssm.enable is true without offload', async () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
             const appDefinition = {
                 ssm: { enable: true },
                 integrations: []
@@ -1070,12 +1081,10 @@ describe('composeServerlessDefinition', () => {
 
             const result = await composeServerlessDefinition(appDefinition);
 
-            // Check lambda layers
-            expect(result.provider.layers).toEqual([
-                'arn:aws:lambda:${self:provider.region}:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11'
-            ]);
+            // We deliberately do NOT use the AWS Parameters-and-Secrets extension layer
+            expect(result.provider.layers).toBeUndefined();
 
-            // Check IAM permissions
+            // Broad read grant present
             const ssmPermission = result.provider.iamRoleStatements.find(
                 statement => statement.Action.includes('ssm:GetParameter')
             );
@@ -1086,13 +1095,56 @@ describe('composeServerlessDefinition', () => {
                     'ssm:GetParameters',
                     'ssm:GetParametersByPath'
                 ],
-                Resource: [
-                    'arn:aws:ssm:${self:provider.region}:*:parameter/${self:service}/${self:provider.stage}/*'
-                ]
+                Resource: {
+                    'Fn::Sub': 'arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/*'
+                }
             });
 
-            // Check environment variable
-            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBe('/${self:service}/${self:provider.stage}');
+            // No offload markers -> no offload env vars
+            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBeUndefined();
+            expect(result.provider.environment.FRIGG_SSM_OFFLOADED_KEYS).toBeUndefined();
+        });
+
+        it('should offload marked keys and expose prefix + offloaded keys env vars', async () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm', BAR: true },
+                integrations: []
+            };
+
+            const result = await composeServerlessDefinition(appDefinition);
+
+            // BAR stays in the Lambda env, FOO is offloaded out of it
+            expect(result.provider.environment.BAR).toBe("${env:BAR, ''}");
+            expect(result.provider.environment.FOO).toBeUndefined();
+
+            // Offload env contract
+            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBe(
+                '/frigg/${self:service}/${self:provider.stage}'
+            );
+            expect(result.provider.environment.FRIGG_SSM_OFFLOADED_KEYS).toBe('FOO');
+
+            // Prefix-scoped read grant present alongside the broad grant
+            const scoped = result.provider.iamRoleStatements.find(
+                statement => statement.Resource === 'arn:aws:ssm:${self:provider.region}:${aws:accountId}:parameter/frigg/${self:service}/${self:provider.stage}/*'
+            );
+            expect(scoped).toBeDefined();
+        });
+
+        it('should not add offload env vars when ssm.enable is true but nothing is marked', async () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { BAR: true },
+                integrations: []
+            };
+
+            const result = await composeServerlessDefinition(appDefinition);
+
+            expect(result.provider.environment.BAR).toBe("${env:BAR, ''}");
+            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBeUndefined();
+            expect(result.provider.environment.FRIGG_SSM_OFFLOADED_KEYS).toBeUndefined();
         });
 
         it('should not add SSM configuration when ssm.enable is false', async () => {
@@ -1397,9 +1449,12 @@ describe('composeServerlessDefinition', () => {
             expect(result.provider.environment.KMS_KEY_ARN).toBeDefined();
             expect(result.custom.kmsGrants).toBeDefined();
 
-            // SSM
-            expect(result.provider.layers).toBeDefined();
-            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBeDefined();
+            // SSM (enabled without offload markers -> broad grant only, no offload env vars)
+            const ssmPermission = result.provider.iamRoleStatements.find(
+                statement => statement.Action && statement.Action.includes('ssm:GetParameter')
+            );
+            expect(ssmPermission).toBeDefined();
+            expect(result.provider.environment.SSM_PARAMETER_PREFIX).toBeUndefined();
 
             // Integration
             expect(result.functions.testIntegration).toBeDefined();

package/infrastructure/integration.test.js

@@ -108,11 +108,9 @@ describe('VPC/KMS/SSM Integration Tests', () => {
             );
             expect(kmsPermission).toBeDefined();
 
-            // Verify SSM configuration
-            expect(serverlessConfig.provider.layers).toEqual([
-                'arn:aws:lambda:${self:provider.region}:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11'
-            ]);
-            expect(serverlessConfig.provider.environment.SSM_PARAMETER_PREFIX).toBe('/${self:service}/${self:provider.stage}');
+            // Verify SSM configuration (enabled without offload markers -> broad grant only)
+            expect(serverlessConfig.provider.layers).toBeUndefined();
+            expect(serverlessConfig.provider.environment.SSM_PARAMETER_PREFIX).toBeUndefined();
 
             // Verify SSM IAM permissions
             const ssmPermission = serverlessConfig.provider.iamRoleStatements.find(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.623.b39b42d.0",
+  "version": "2.0.0--canary.625.950ba82.0",
   "bin": {
     "frigg": "./frigg-cli/index.js"
   },
@@ -21,13 +21,14 @@
     "@aws-sdk/client-rds": "^3.906.0",
     "@aws-sdk/client-s3": "^3.917.0",
     "@aws-sdk/client-secrets-manager": "^3.906.0",
+    "@aws-sdk/client-ssm": "^3.906.0",
     "@aws-sdk/client-sts": "^3.835.0",
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "2.0.0--canary.623.b39b42d.0",
-    "@friggframework/schemas": "2.0.0--canary.623.b39b42d.0",
-    "@friggframework/test": "2.0.0--canary.623.b39b42d.0",
+    "@friggframework/core": "2.0.0--canary.625.950ba82.0",
+    "@friggframework/schemas": "2.0.0--canary.625.950ba82.0",
+    "@friggframework/test": "2.0.0--canary.625.950ba82.0",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.18.0",
@@ -55,8 +56,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0--canary.623.b39b42d.0",
-    "@friggframework/prettier-config": "2.0.0--canary.623.b39b42d.0",
+    "@friggframework/eslint-config": "2.0.0--canary.625.950ba82.0",
+    "@friggframework/prettier-config": "2.0.0--canary.625.950ba82.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -88,5 +89,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b39b42dc96ec3dfe4963a63b27468cd1b9c107c6"
+  "gitHead": "950ba828b2885a01768dbfbee5a1fd531efb89ab"
 }