@friggframework/devtools 2.0.0--canary.625.27a7e7a.0 → 2.0.0--canary.625.3f500f2.0

package/infrastructure/__tests__/ssm-preload-node-options.test.js

@@ -0,0 +1,79 @@
+/**
+ * The SSM INIT preload (NODE_OPTIONS=--import) must be scoped to skipEsbuild
+ * functions only. esbuild-bundled functions (e.g. defaultWebsocket) do not
+ * package the preload .mjs, and a missing --import target fatally aborts Node
+ * startup — so a global NODE_OPTIONS would brick them (ADR-027 review finding).
+ */
+
+const { composeServerlessDefinition } = require('../infrastructure-composer');
+
+jest.mock('../domains/shared/resource-discovery', () => {
+    const original = jest.requireActual('../domains/shared/resource-discovery');
+    return {
+        ...original,
+        gatherDiscoveredResources: jest.fn().mockResolvedValue({
+            defaultVpcId: 'vpc-123456',
+            defaultSecurityGroupId: 'sg-123456',
+            privateSubnetId1: 'subnet-1',
+            privateSubnetId2: 'subnet-2',
+            defaultKmsKeyId:
+                'arn:aws:kms:us-east-1:123456789012:key/abc-123',
+            auroraClusterEndpoint: 'c.cluster-x.us-east-1.rds.amazonaws.com',
+            auroraPort: 5432,
+        }),
+    };
+});
+
+const buildApp = (overrides = {}) => ({
+    name: 'preload-test',
+    provider: 'aws',
+    usePrismaLambdaLayer: false,
+    encryption: { fieldLevelEncryptionMethod: 'aes' },
+    vpc: { enable: false },
+    database: { postgres: { enable: true } },
+    websockets: { enable: true },
+    integrations: [{ Definition: { name: 'hubspot' } }],
+    ...overrides,
+});
+
+const IMPORT_FRAGMENT = '--import file:///var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
+
+describe('SSM preload NODE_OPTIONS scoping', () => {
+    beforeEach(() => {
+        process.argv = ['node', 'test'];
+        delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+    });
+
+    it('sets NODE_OPTIONS --import on skipEsbuild functions and NOT on esbuild-bundled ones when offload is active', async () => {
+        const definition = await composeServerlessDefinition(
+            buildApp({
+                ssm: { enable: true },
+                environment: { HUBSPOT_SECRET: 'ssm' },
+            })
+        );
+        const fns = definition.functions;
+
+        // skipEsbuild handlers (auth/user/health + integration) package the
+        // preload → they get the flag.
+        expect(fns.auth.skipEsbuild).toBe(true);
+        expect(fns.auth.environment.NODE_OPTIONS).toBe(IMPORT_FRAGMENT);
+        expect(fns.hubspot.environment.NODE_OPTIONS).toBe(IMPORT_FRAGMENT);
+
+        // defaultWebsocket is esbuild-bundled (no skipEsbuild) → MUST NOT get it.
+        expect(fns.defaultWebsocket.skipEsbuild).toBeFalsy();
+        expect(fns.defaultWebsocket.environment?.NODE_OPTIONS).toBeUndefined();
+
+        // Never global.
+        expect(definition.provider.environment.NODE_OPTIONS).toBeUndefined();
+    });
+
+    it('sets no NODE_OPTIONS anywhere when offload is inactive', async () => {
+        const definition = await composeServerlessDefinition(
+            buildApp({ ssm: { enable: true } }) // enabled, but no 'ssm' keys
+        );
+        for (const fn of Object.values(definition.functions)) {
+            expect(fn.environment?.NODE_OPTIONS).toBeUndefined();
+        }
+        expect(definition.provider.environment.NODE_OPTIONS).toBeUndefined();
+    });
+});

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

@@ -16,6 +16,19 @@ 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.
@@ -172,4 +185,6 @@ module.exports = {
     validateOffloadConfig,
     FRAMEWORK_ENV_BLOCKLIST,
     DEFAULT_PARAMETER_PREFIX,
+    SSM_PRELOAD_PATH,
+    SSM_PRELOAD_NODE_OPTIONS,
 };

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

@@ -93,6 +93,13 @@ class SsmBuilder extends InfrastructureBuilder {
             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.

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

@@ -234,6 +234,19 @@ describe('SsmBuilder', () => {
             expect(result.environment.FRIGG_SSM_OFFLOADED_KEYS).toBe('BAR,FOO');
         });
 
+        it('does not set NODE_OPTIONS globally (the composer scopes it to skipEsbuild functions)', async () => {
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = await ssmBuilder.build(appDefinition, {});
+
+            // NODE_OPTIONS=--import would fatally abort esbuild-bundled functions
+            // that lack the preload file, so it must never be provider-global.
+            expect(result.environment.NODE_OPTIONS).toBeUndefined();
+        });
+
         it('should add a prefix-scoped read statement while retaining the broad grant by default', async () => {
             const appDefinition = {
                 ssm: { enable: true },

package/infrastructure/infrastructure-composer.js

@@ -21,6 +21,30 @@ const { AdminScriptBuilder } = require('./domains/admin-scripts/admin-script-bui
 
 // 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).
+ */
+function applySsmPreloadNodeOptions(appDefinition, functions) {
+    if (!isSsmOffloadActive(appDefinition)) {
+        return;
+    }
+    for (const fn of Object.values(functions)) {
+        if (fn.skipEsbuild) {
+            fn.environment = fn.environment || {};
+            fn.environment.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');
@@ -80,6 +104,7 @@ const composeServerlessDefinition = async (AppDefinition) => {
         definition.functions,
         merged.functionEnvironments
     );
+    applySsmPreloadNodeOptions(AppDefinition, definition.functions);
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.625.27a7e7a.0",
+  "version": "2.0.0--canary.625.3f500f2.0",
   "bin": {
     "frigg": "./frigg-cli/index.js"
   },
@@ -26,9 +26,9 @@
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "2.0.0--canary.625.27a7e7a.0",
-    "@friggframework/schemas": "2.0.0--canary.625.27a7e7a.0",
-    "@friggframework/test": "2.0.0--canary.625.27a7e7a.0",
+    "@friggframework/core": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/schemas": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/test": "2.0.0--canary.625.3f500f2.0",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.18.0",
@@ -56,8 +56,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0--canary.625.27a7e7a.0",
-    "@friggframework/prettier-config": "2.0.0--canary.625.27a7e7a.0",
+    "@friggframework/eslint-config": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/prettier-config": "2.0.0--canary.625.3f500f2.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -89,5 +89,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "27a7e7ae02d6dc5789f5aba0fe5c4cf82320dc38"
+  "gitHead": "3f500f202c8dcf2210c07835c76abbab30e0d0ee"
 }