@friggframework/devtools 2.0.0--canary.625.8f60019.0 → 2.0.0--canary.625.0de0db4.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/networking/vpc-discovery.js

@@ -123,6 +123,10 @@ class VpcDiscovery {
                 const sqsEndpoint = rawResources.vpcEndpoints.find(
                     ep => ep.ServiceName && ep.ServiceName.includes('.sqs')
                 );
+                // endsWith avoids matching sibling services like `.ssmmessages`
+                const ssmEndpoint = rawResources.vpcEndpoints.find(
+                    ep => ep.ServiceName && ep.ServiceName.endsWith('.ssm')
+                );
 
                 if (s3Endpoint) {
                     result.s3VpcEndpointId = s3Endpoint.VpcEndpointId;
@@ -139,6 +143,9 @@ class VpcDiscovery {
                 if (sqsEndpoint) {
                     result.sqsVpcEndpointId = sqsEndpoint.VpcEndpointId;
                 }
+                if (ssmEndpoint) {
+                    result.ssmVpcEndpointId = ssmEndpoint.VpcEndpointId;
+                }
             }
 
             console.log(`  ✓ Found VPC: ${result.defaultVpcId}`);
@@ -151,8 +158,8 @@ class VpcDiscovery {
             if (result.existingNatGatewayId) {
                 console.log(`  ✓ Found NAT Gateway: ${result.existingNatGatewayId}`);
             }
-            if (result.s3VpcEndpointId || result.dynamodbVpcEndpointId || result.kmsVpcEndpointId || result.secretsManagerVpcEndpointId || result.sqsVpcEndpointId) {
-                console.log(`  ✓ Found VPC Endpoints: S3=${result.s3VpcEndpointId ? 'Yes' : 'No'}, DynamoDB=${result.dynamodbVpcEndpointId ? 'Yes' : 'No'}, KMS=${result.kmsVpcEndpointId ? 'Yes' : 'No'}, SecretsManager=${result.secretsManagerVpcEndpointId ? 'Yes' : 'No'}, SQS=${result.sqsVpcEndpointId ? 'Yes' : 'No'}`);
+            if (result.s3VpcEndpointId || result.dynamodbVpcEndpointId || result.kmsVpcEndpointId || result.secretsManagerVpcEndpointId || result.sqsVpcEndpointId || result.ssmVpcEndpointId) {
+                console.log(`  ✓ Found VPC Endpoints: S3=${result.s3VpcEndpointId ? 'Yes' : 'No'}, DynamoDB=${result.dynamodbVpcEndpointId ? 'Yes' : 'No'}, KMS=${result.kmsVpcEndpointId ? 'Yes' : 'No'}, SecretsManager=${result.secretsManagerVpcEndpointId ? 'Yes' : 'No'}, SQS=${result.sqsVpcEndpointId ? 'Yes' : 'No'}, SSM=${result.ssmVpcEndpointId ? 'Yes' : 'No'}`);
             }
 
             return result;

package/infrastructure/domains/networking/vpc-discovery.test.js

@@ -253,7 +253,7 @@ describe('VpcDiscovery', () => {
             expect(mockProvider.discoverVpc).toHaveBeenCalledWith(config);
         });
 
-        it('should discover all VPC endpoints (S3, DynamoDB, KMS, Secrets Manager)', async () => {
+        it('should discover all VPC endpoints (S3, DynamoDB, KMS, Secrets Manager, SQS, SSM)', async () => {
             mockProvider.discoverVpc.mockResolvedValue({
                 vpcId: 'vpc-123',
                 vpcCidr: '10.0.0.0/16',
@@ -283,6 +283,22 @@ describe('VpcDiscovery', () => {
                         ServiceName: 'com.amazonaws.us-east-1.secretsmanager',
                         State: 'available',
                     },
+                    {
+                        VpcEndpointId: 'vpce-sqs-def',
+                        ServiceName: 'com.amazonaws.us-east-1.sqs',
+                        State: 'available',
+                    },
+                    // ssmmessages must NOT be mistaken for the ssm endpoint
+                    {
+                        VpcEndpointId: 'vpce-ssmmessages-000',
+                        ServiceName: 'com.amazonaws.us-east-1.ssmmessages',
+                        State: 'available',
+                    },
+                    {
+                        VpcEndpointId: 'vpce-ssm-ghi',
+                        ServiceName: 'com.amazonaws.us-east-1.ssm',
+                        State: 'available',
+                    },
                 ],
             });
 
@@ -292,6 +308,8 @@ describe('VpcDiscovery', () => {
             expect(result.dynamodbVpcEndpointId).toBe('vpce-ddb-456');
             expect(result.kmsVpcEndpointId).toBe('vpce-kms-789');
             expect(result.secretsManagerVpcEndpointId).toBe('vpce-sm-abc');
+            expect(result.sqsVpcEndpointId).toBe('vpce-sqs-def');
+            expect(result.ssmVpcEndpointId).toBe('vpce-ssm-ghi');
         });
 
         it('should handle partial VPC endpoint discovery', async () => {

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.
@@ -81,7 +94,7 @@ function getOffloadedKeys(appDefinition = {}) {
         keys.add(key);
     }
 
-    return [...keys].sort();
+    return [...keys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 /**
@@ -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

@@ -16,11 +16,6 @@ const {
     validateOffloadConfig,
 } = require('./offload-utils');
 
-// INIT-phase preload shipped in @friggframework/core, packaged into every
-// skipEsbuild handler at this stable path (LAMBDA_TASK_ROOT = /var/task).
-const SSM_PRELOAD_PATH =
-    '/var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
-
 class SsmBuilder extends InfrastructureBuilder {
     constructor() {
         super();
@@ -98,15 +93,12 @@ class SsmBuilder extends InfrastructureBuilder {
             result.environment.SSM_PARAMETER_PREFIX = prefix;
             result.environment.FRIGG_SSM_OFFLOADED_KEYS = offloadedKeys.join(',');
 
-            // Populate offloaded values into process.env during Lambda INIT,
-            // BEFORE app modules load. api-modules capture OAuth client
-            // credentials at module-require time (top-level Definition.env), so
-            // the handler-time loader (parametersToEnv) is too late for them.
-            // NODE_OPTIONS=--import runs this ESM preload (top-level await) before
-            // the entry module. Shipped in @friggframework/core (packaged into
-            // every skipEsbuild handler at a stable path). Appended to any
-            // app-provided NODE_OPTIONS.
-            result.environment.NODE_OPTIONS = `\${env:NODE_OPTIONS, ''} --import file://${SSM_PRELOAD_PATH}`;
+            // 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

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

@@ -234,7 +234,7 @@ describe('SsmBuilder', () => {
             expect(result.environment.FRIGG_SSM_OFFLOADED_KEYS).toBe('BAR,FOO');
         });
 
-        it('sets NODE_OPTIONS to --import the INIT preload (appended to any app value)', async () => {
+        it('does not set NODE_OPTIONS globally (the composer scopes it to skipEsbuild functions)', async () => {
             const appDefinition = {
                 ssm: { enable: true },
                 environment: { FOO: 'ssm' },
@@ -242,18 +242,8 @@ describe('SsmBuilder', () => {
 
             const result = await ssmBuilder.build(appDefinition, {});
 
-            expect(result.environment.NODE_OPTIONS).toContain('--import');
-            expect(result.environment.NODE_OPTIONS).toContain(
-                '@friggframework/core/core/ssm-preload.mjs'
-            );
-            // Appends to any app-provided NODE_OPTIONS rather than clobbering it.
-            expect(result.environment.NODE_OPTIONS).toContain(
-                "${env:NODE_OPTIONS, ''}"
-            );
-        });
-
-        it('does not set NODE_OPTIONS when no keys are offloaded', async () => {
-            const result = await ssmBuilder.build({ ssm: { enable: true } }, {});
+            // 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();
         });
 

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

@@ -703,7 +703,10 @@ function generateIAMCloudFormation(options = {}) {
                                       },
                                   ],
                             Condition: {
-                                StringEquals: {
+                                // StringLike: kms:ViaService is regional
+                                // (ssm.us-east-1.amazonaws.com), so the wildcard
+                                // must be matched, not compared literally.
+                                StringLike: {
                                     'kms:ViaService': [
                                         'ssm.*.amazonaws.com',
                                     ],

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

@@ -166,6 +166,16 @@ describe('IAM Generator', () => {
             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/*');
+
+            // The regional ViaService wildcard must be matched with StringLike;
+            // StringEquals would compare literally and never match
+            // ssm.<region>.amazonaws.com, denying the SecureString KMS call.
+            const ssmKmsBlock = yaml.slice(
+                yaml.indexOf('FriggSSMParameterKMSEncryption'),
+                yaml.indexOf('FriggSSMParameterKMSEncryption') + 600
+            );
+            expect(ssmKmsBlock).toContain('StringLike');
+            expect(ssmKmsBlock).not.toContain('StringEquals');
         });
 
         it('should scope the SSM KMS grant to ssm.kmsKeyArn when provided', () => {

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

@@ -375,7 +375,9 @@ Resources:
             Resource:
               - !Sub 'arn:aws:kms:*:${AWS::AccountId}:key/*'
             Condition:
-              StringEquals:
+              # StringLike: kms:ViaService is regional (ssm.us-east-1.amazonaws.com),
+              # so the wildcard must be matched, not compared literally.
+              StringLike:
                 'kms:ViaService':
                   - 'ssm.*.amazonaws.com'
 

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

@@ -264,7 +264,7 @@
         "arn:aws:kms:*:*:key/*"
       ],
       "Condition": {
-        "StringEquals": {
+        "StringLike": {
           "kms:ViaService": [
             "lambda.*.amazonaws.com",
             "s3.*.amazonaws.com",

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.8f60019.0",
+  "version": "2.0.0--canary.625.0de0db4.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.8f60019.0",
-    "@friggframework/schemas": "2.0.0--canary.625.8f60019.0",
-    "@friggframework/test": "2.0.0--canary.625.8f60019.0",
+    "@friggframework/core": "2.0.0--canary.625.0de0db4.0",
+    "@friggframework/schemas": "2.0.0--canary.625.0de0db4.0",
+    "@friggframework/test": "2.0.0--canary.625.0de0db4.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.8f60019.0",
-    "@friggframework/prettier-config": "2.0.0--canary.625.8f60019.0",
+    "@friggframework/eslint-config": "2.0.0--canary.625.0de0db4.0",
+    "@friggframework/prettier-config": "2.0.0--canary.625.0de0db4.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": "8f600193664963446e2c59c4b05ee076b0fbdc2a"
+  "gitHead": "0de0db43a6403eb99de205e24fcde7e9761ba4f6"
 }