@friggframework/devtools 2.0.0-next.101 → 2.0.0-next.103

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,44 @@ 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 {
+    isSsmOffloadActive,
+    SSM_PRELOAD_NODE_OPTIONS,
+} = require('./domains/parameters/offload-utils');
+
+/**
+ * Load the SSM INIT preload (NODE_OPTIONS=--import) on skipEsbuild handlers
+ * only. Those package the full node_modules tree, so the preload .mjs is
+ * present at /var/task. esbuild-bundled functions (e.g. defaultWebsocket,
+ * adopter custom functions) do NOT ship it — and a missing --import target is a
+ * fatal Node startup error — so they are left with the handler-time loader
+ * fallback instead.
+ *
+ * Set at function scope (function env wins over provider env), APPENDED to any
+ * NODE_OPTIONS already on the function or provider — so an app's own flags
+ * (OTel auto-instrumentation, source maps, memory tuning) survive instead of
+ * being clobbered. A function-level assignment shadows provider env in Lambda,
+ * so the provider value must be folded in here. Only a value already in the
+ * definition is appended — never a synthesized ${env:NODE_OPTIONS}, which would
+ * leak the deploy host's shell into every Lambda.
+ */
+function applySsmPreloadNodeOptions(appDefinition, functions, providerEnvironment = {}) {
+    if (!isSsmOffloadActive(appDefinition)) {
+        return;
+    }
+    for (const fn of Object.values(functions)) {
+        if (!fn.skipEsbuild) {
+            continue;
+        }
+        fn.environment = fn.environment || {};
+        const existing =
+            fn.environment.NODE_OPTIONS ?? providerEnvironment.NODE_OPTIONS;
+        fn.environment.NODE_OPTIONS = existing
+            ? `${existing} ${SSM_PRELOAD_NODE_OPTIONS}`
+            : SSM_PRELOAD_NODE_OPTIONS;
+    }
+}
 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 +113,15 @@ 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
+    );
+    applySsmPreloadNodeOptions(
+        AppDefinition,
+        definition.functions,
+        definition.provider.environment
+    );
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;
@@ -117,5 +164,5 @@ const composeServerlessDefinition = async (AppDefinition) => {
     return definition;
 };
 
-module.exports = { composeServerlessDefinition };
+module.exports = { composeServerlessDefinition, applySsmPreloadNodeOptions };
 

package/infrastructure/infrastructure-composer.test.js

@@ -1,4 +1,10 @@
-const { composeServerlessDefinition } = require('./infrastructure-composer');
+const {
+    composeServerlessDefinition,
+    applySsmPreloadNodeOptions,
+} = require('./infrastructure-composer');
+const {
+    SSM_PRELOAD_NODE_OPTIONS,
+} = require('./domains/parameters/offload-utils');
 
 // Helper to build discovery responses with overridable fields
 const createDiscoveryResponse = (overrides = {}) => ({
@@ -1062,7 +1068,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 +1087,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 +1101,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 +1455,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();
@@ -1894,3 +1955,88 @@ describe('composeServerlessDefinition', () => {
         });
     });
 });
+
+describe('applySsmPreloadNodeOptions', () => {
+    const appDefinition = {
+        ssm: { enable: true },
+        environment: { FOO: 'ssm' },
+    };
+    const savedSkip = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+    beforeEach(() => {
+        delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+    });
+
+    afterEach(() => {
+        if (savedSkip === undefined) {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+        } else {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = savedSkip;
+        }
+    });
+
+    it('sets the preload NODE_OPTIONS on a skipEsbuild function with no existing value', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(appDefinition, functions);
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            SSM_PRELOAD_NODE_OPTIONS
+        );
+    });
+
+    it('appends to an existing function-level NODE_OPTIONS instead of clobbering it', () => {
+        const functions = {
+            auth: {
+                skipEsbuild: true,
+                environment: { NODE_OPTIONS: '--enable-source-maps' },
+            },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions);
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--enable-source-maps ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('folds in a provider-level NODE_OPTIONS (which the function env would otherwise shadow)', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--require ./otel.js',
+        });
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--require ./otel.js ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('prefers a function-level value over the provider-level one', () => {
+        const functions = {
+            auth: {
+                skipEsbuild: true,
+                environment: { NODE_OPTIONS: '--fn-flag' },
+            },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--provider-flag',
+        });
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--fn-flag ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('never touches esbuild-bundled functions', () => {
+        const functions = {
+            websocket: { environment: { NODE_OPTIONS: '--keep-me' } },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--provider',
+        });
+        expect(functions.websocket.environment.NODE_OPTIONS).toBe('--keep-me');
+    });
+
+    it('is a no-op when offload is inactive', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(
+            { ssm: { enable: true } }, // no offloaded keys → inactive
+            functions
+        );
+        expect(functions.auth.environment).toBeUndefined();
+    });
+});

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-next.101",
+  "version": "2.0.0-next.103",
   "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-next.101",
-    "@friggframework/schemas": "2.0.0-next.101",
-    "@friggframework/test": "2.0.0-next.101",
+    "@friggframework/core": "2.0.0-next.103",
+    "@friggframework/schemas": "2.0.0-next.103",
+    "@friggframework/test": "2.0.0-next.103",
     "@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-next.101",
-    "@friggframework/prettier-config": "2.0.0-next.101",
+    "@friggframework/eslint-config": "2.0.0-next.103",
+    "@friggframework/prettier-config": "2.0.0-next.103",
     "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": "63e9d85c59dc39bb745091911c8149a0de2b3cff"
+  "gitHead": "9fc434b0c6e1323bd16be165d311b6880a23de12"
 }