@friggframework/devtools 2.0.0-next.11 → 2.0.0-next.110

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

@@ -0,0 +1,190 @@
+/**
+ * SSM Offload Utilities
+ *
+ * Shared helpers for the SSM Parameter Store offload feature. A variable is
+ * "offloaded" when its value lives in Parameter Store and is fetched by the
+ * runtime at cold start instead of being baked into the Lambda environment
+ * (which counts against the hard 4KB env-var limit).
+ *
+ * Consumed by the SsmBuilder, the environment builder, and the
+ * `frigg ssm push` CLI command so they all agree on the offload key set and
+ * parameter naming.
+ */
+
+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.
+const FRAMEWORK_ENV_BLOCKLIST = new Set([
+    'STAGE',
+    'FRIGG_STACK',
+    'FRIGG_STAGE',
+    'FRIGG_REGION',
+    'KMS_KEY_ARN',
+    'AES_KEY',
+    'AES_KEY_ID',
+    'DATABASE_URL',
+    'DATABASE_HOST',
+    'DATABASE_PORT',
+    'DATABASE_USER',
+    'DATABASE_PASSWORD',
+    'DATABASE_SECRET_ARN',
+    'DB_TYPE',
+    'MONGO_URI',
+    'SECRET_ARN',
+    'SSM_PARAMETER_PREFIX',
+    'FRIGG_SSM_OFFLOADED_KEYS',
+    'FRIGG_SSM_CACHE_TTL',
+    'WORKER_FUNCTION_NAME',
+    // Reserved AWS Lambda runtime variables
+    '_HANDLER',
+    '_X_AMZN_TRACE_ID',
+    'AWS_DEFAULT_REGION',
+    'AWS_EXECUTION_ENV',
+    'AWS_REGION',
+    'AWS_LAMBDA_FUNCTION_NAME',
+    'AWS_LAMBDA_FUNCTION_MEMORY_SIZE',
+    'AWS_LAMBDA_FUNCTION_VERSION',
+    'AWS_LAMBDA_INITIALIZATION_TYPE',
+    'AWS_LAMBDA_LOG_GROUP_NAME',
+    'AWS_LAMBDA_LOG_STREAM_NAME',
+    'AWS_ACCESS_KEY',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+]);
+
+/**
+ * Union of keys marked for SSM offload, sorted for deterministic output.
+ * Sources: appDefinition.environment values === 'ssm' and
+ * appDefinition.ssm.parameters keys. Does NOT filter invalid/blocklisted
+ * keys — use validateOffloadConfig() to surface those as errors instead of
+ * silently dropping them.
+ *
+ * @param {Object} appDefinition
+ * @returns {string[]}
+ */
+function getOffloadedKeys(appDefinition = {}) {
+    const keys = new Set();
+
+    for (const [key, value] of Object.entries(
+        appDefinition.environment || {}
+    )) {
+        if (value === 'ssm') keys.add(key);
+    }
+
+    for (const key of Object.keys(appDefinition.ssm?.parameters || {})) {
+        keys.add(key);
+    }
+
+    return [...keys].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * Parameter path prefix under which offloaded values are stored. The default
+ * uses serverless variables resolved at package time and stays inside the
+ * *frigg* scope of the generated deployment IAM policies.
+ *
+ * @param {Object} appDefinition
+ * @returns {string}
+ */
+function getParameterPrefix(appDefinition = {}) {
+    const prefix =
+        appDefinition.ssm?.parameterPrefix || DEFAULT_PARAMETER_PREFIX;
+    return prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+}
+
+/**
+ * Resolve the parameter prefix to a concrete path outside a serverless
+ * build (e.g. in the CLI), substituting the serverless variables the
+ * default prefix uses.
+ *
+ * @param {Object} appDefinition
+ * @param {string} stage
+ * @returns {string}
+ */
+function resolveParameterPrefix(appDefinition = {}, stage) {
+    return getParameterPrefix(appDefinition)
+        .replaceAll('${self:service}', appDefinition.name)
+        .replaceAll('${self:provider.stage}', stage);
+}
+
+/**
+ * Whether the offload feature is active for this build: SSM enabled, at
+ * least one key marked, and not running in local mode.
+ *
+ * @param {Object} appDefinition
+ * @returns {boolean}
+ */
+function isSsmOffloadActive(appDefinition = {}) {
+    if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') return false;
+    if (appDefinition.ssm?.enable !== true) return false;
+    return getOffloadedKeys(appDefinition).length > 0;
+}
+
+/**
+ * Validate the offload configuration. Returns errors (not warnings) for
+ * misconfigurations that would silently lose variables at runtime.
+ *
+ * @param {Object} appDefinition
+ * @returns {{errors: string[]}}
+ */
+function validateOffloadConfig(appDefinition = {}) {
+    const errors = [];
+    const offloadedKeys = getOffloadedKeys(appDefinition);
+
+    if (offloadedKeys.length === 0) {
+        return { errors };
+    }
+
+    if (appDefinition.ssm?.enable !== true) {
+        errors.push(
+            `Environment keys are marked for SSM offload (${offloadedKeys.join(
+                ', '
+            )}) but ssm.enable is not true. Set ssm: { enable: true } in the app definition.`
+        );
+    }
+
+    for (const key of offloadedKeys) {
+        if (FRAMEWORK_ENV_BLOCKLIST.has(key)) {
+            errors.push(
+                `${key} is a framework-managed environment variable and cannot be offloaded to SSM.`
+            );
+        } else if (!ENV_NAME_PATTERN.test(key)) {
+            errors.push(
+                `'${key}' is not a valid environment variable name (expected ${ENV_NAME_PATTERN}); it cannot be offloaded to SSM.`
+            );
+        }
+    }
+
+    return { errors };
+}
+
+module.exports = {
+    getOffloadedKeys,
+    getParameterPrefix,
+    resolveParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+    FRAMEWORK_ENV_BLOCKLIST,
+    DEFAULT_PARAMETER_PREFIX,
+    SSM_PRELOAD_PATH,
+    SSM_PRELOAD_NODE_OPTIONS,
+};

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

@@ -0,0 +1,193 @@
+const {
+    getOffloadedKeys,
+    getParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+    FRAMEWORK_ENV_BLOCKLIST,
+} = require('./offload-utils');
+
+describe('offload-utils', () => {
+    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('getOffloadedKeys', () => {
+        it('returns empty array when nothing is marked', () => {
+            expect(getOffloadedKeys({})).toEqual([]);
+            expect(
+                getOffloadedKeys({ environment: { MY_VAR: true } })
+            ).toEqual([]);
+        });
+
+        it("collects environment keys marked 'ssm'", () => {
+            const keys = getOffloadedKeys({
+                environment: { B_VAR: 'ssm', A_VAR: 'ssm', PLAIN: true },
+            });
+            expect(keys).toEqual(['A_VAR', 'B_VAR']);
+        });
+
+        it('collects ssm.parameters keys', () => {
+            const keys = getOffloadedKeys({
+                ssm: {
+                    enable: true,
+                    parameters: { MY_SECRET: { type: 'SecureString' } },
+                },
+            });
+            expect(keys).toEqual(['MY_SECRET']);
+        });
+
+        it('unions and dedupes both sources, sorted', () => {
+            const keys = getOffloadedKeys({
+                environment: { SHARED: 'ssm', ENV_ONLY: 'ssm' },
+                ssm: {
+                    enable: true,
+                    parameters: {
+                        SHARED: { type: 'SecureString' },
+                        PARAM_ONLY: { type: 'String' },
+                    },
+                },
+            });
+            expect(keys).toEqual(['ENV_ONLY', 'PARAM_ONLY', 'SHARED']);
+        });
+    });
+
+    describe('getParameterPrefix', () => {
+        it('defaults to the frigg-scoped serverless-variable path', () => {
+            expect(getParameterPrefix({})).toBe(
+                '/frigg/${self:service}/${self:provider.stage}'
+            );
+        });
+
+        it('honors ssm.parameterPrefix override', () => {
+            expect(
+                getParameterPrefix({ ssm: { parameterPrefix: '/custom/x' } })
+            ).toBe('/custom/x');
+        });
+
+        it('strips a trailing slash from the override', () => {
+            expect(
+                getParameterPrefix({ ssm: { parameterPrefix: '/custom/x/' } })
+            ).toBe('/custom/x');
+        });
+    });
+
+    describe('resolveParameterPrefix', () => {
+        const { resolveParameterPrefix } = require('./offload-utils');
+
+        it('resolves the default prefix with service and stage', () => {
+            expect(
+                resolveParameterPrefix({ name: 'my-app' }, 'prod')
+            ).toBe('/frigg/my-app/prod');
+        });
+
+        it('resolves serverless tokens inside a custom prefix', () => {
+            expect(
+                resolveParameterPrefix(
+                    {
+                        name: 'my-app',
+                        ssm: {
+                            parameterPrefix:
+                                '/x/${self:service}/${self:provider.stage}',
+                        },
+                    },
+                    'dev'
+                )
+            ).toBe('/x/my-app/dev');
+        });
+
+        it('passes literal custom prefixes through', () => {
+            expect(
+                resolveParameterPrefix(
+                    { name: 'my-app', ssm: { parameterPrefix: '/plain/path' } },
+                    'dev'
+                )
+            ).toBe('/plain/path');
+        });
+    });
+
+    describe('isSsmOffloadActive', () => {
+        const offloadApp = {
+            ssm: { enable: true },
+            environment: { MY_SECRET: 'ssm' },
+        };
+
+        it('is true when ssm enabled and offload set non-empty', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(isSsmOffloadActive(offloadApp)).toBe(true);
+        });
+
+        it('is false without ssm.enable', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(
+                isSsmOffloadActive({ environment: { MY_SECRET: 'ssm' } })
+            ).toBe(false);
+        });
+
+        it('is false when nothing is offloaded', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(isSsmOffloadActive({ ssm: { enable: true } })).toBe(false);
+        });
+
+        it('is false in local mode (FRIGG_SKIP_AWS_DISCOVERY)', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            expect(isSsmOffloadActive(offloadApp)).toBe(false);
+        });
+    });
+
+    describe('validateOffloadConfig', () => {
+        it('passes for a clean offload config', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: { enable: true },
+                environment: { MY_SECRET: 'ssm' },
+            });
+            expect(errors).toEqual([]);
+        });
+
+        it('errors when offload markers exist without ssm.enable', () => {
+            const { errors } = validateOffloadConfig({
+                environment: { MY_SECRET: 'ssm' },
+            });
+            expect(errors.join(' ')).toMatch(/ssm\.enable/);
+        });
+
+        it('errors on framework-managed (blocklisted) keys', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: { enable: true },
+                environment: { DATABASE_URL: 'ssm' },
+            });
+            expect(errors.join(' ')).toMatch(/DATABASE_URL/);
+        });
+
+        it('errors on keys that are not valid env var names', () => {
+            const { errors } = validateOffloadConfig({
+                ssm: {
+                    enable: true,
+                    parameters: { 'api-keys/foo': { type: 'String' } },
+                },
+            });
+            expect(errors.join(' ')).toMatch(/api-keys\/foo/);
+        });
+    });
+
+    it('blocklist covers the framework-managed keys', () => {
+        for (const key of [
+            'STAGE',
+            'FRIGG_STACK',
+            'KMS_KEY_ARN',
+            'DATABASE_URL',
+            'DATABASE_SECRET_ARN',
+            'SECRET_ARN',
+            'SSM_PARAMETER_PREFIX',
+            'FRIGG_SSM_OFFLOADED_KEYS',
+            'AWS_REGION',
+        ]) {
+            expect(FRAMEWORK_ENV_BLOCKLIST.has(key)).toBe(true);
+        }
+    });
+});

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

@@ -0,0 +1,132 @@
+/**
+ * SSM Parameter Store Builder
+ * 
+ * Domain Layer - Hexagonal Architecture
+ * 
+ * Responsible for:
+ * - Configuring IAM permissions for SSM Parameter Store access
+ * - Setting up SSM parameter references for Lambda functions
+ */
+
+const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+const {
+    getOffloadedKeys,
+    getParameterPrefix,
+    isSsmOffloadActive,
+    validateOffloadConfig,
+} = require('./offload-utils');
+
+class SsmBuilder extends InfrastructureBuilder {
+    constructor() {
+        super();
+        this.name = 'SsmBuilder';
+    }
+
+    shouldExecute(appDefinition) {
+        // Skip SSM in local mode (when FRIGG_SKIP_AWS_DISCOVERY is set)
+        // SSM Parameter Store is an AWS-specific service that should only be used in production
+        if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') {
+            return false;
+        }
+
+        return appDefinition.ssm?.enable === true;
+    }
+
+    validate(appDefinition) {
+        const result = new ValidationResult();
+
+        if (!appDefinition.ssm) {
+            result.addError('SSM configuration is missing');
+            return result;
+        }
+
+        // Validate parameters if provided
+        if (appDefinition.ssm.parameters) {
+            if (typeof appDefinition.ssm.parameters !== 'object' || Array.isArray(appDefinition.ssm.parameters)) {
+                result.addError('ssm.parameters must be an object (not an array)');
+            }
+        }
+
+        for (const error of validateOffloadConfig(appDefinition).errors) {
+            result.addError(error);
+        }
+
+        return result;
+    }
+
+    /**
+     * Build SSM configuration
+     */
+    async build(appDefinition, discoveredResources) {
+        console.log(`\n[${this.name}] Configuring SSM Parameter Store...`);
+
+        const result = {
+            iamStatements: [],
+            environment: {},
+        };
+
+        const ssmActions = [
+            'ssm:GetParameter',
+            'ssm:GetParameters',
+            'ssm:GetParametersByPath',
+        ];
+
+        const offloadActive = isSsmOffloadActive(appDefinition);
+
+        // Broad read grant, unless the app opts into prefix-only access while
+        // offload is active.
+        if (!(appDefinition.ssm.restrictIamToPrefix === true && offloadActive)) {
+            result.iamStatements.push({
+                Effect: 'Allow',
+                Action: ssmActions,
+                Resource: {
+                    'Fn::Sub': 'arn:aws:ssm:${AWS::Region}:${AWS::AccountId}:parameter/*',
+                },
+            });
+            console.log('  ✅ SSM Parameter Store IAM permissions added');
+        }
+
+        if (offloadActive) {
+            const prefix = getParameterPrefix(appDefinition);
+            const offloadedKeys = getOffloadedKeys(appDefinition);
+
+            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.
+            result.iamStatements.push({
+                Effect: 'Allow',
+                Action: ssmActions,
+                Resource: `arn:aws:ssm:\${self:provider.region}:\${aws:accountId}:parameter${prefix}/*`,
+            });
+            console.log(
+                `  ✅ SSM offload enabled for ${offloadedKeys.length} variable(s) under ${prefix}`
+            );
+
+            if (appDefinition.ssm.kmsKeyArn) {
+                result.iamStatements.push({
+                    Effect: 'Allow',
+                    Action: ['kms:Decrypt'],
+                    Resource: appDefinition.ssm.kmsKeyArn,
+                });
+                console.log('  ✅ KMS decrypt permission added for offloaded parameters');
+            }
+        }
+
+        console.log(`[${this.name}] ✅ SSM configuration completed`);
+
+        return result;
+    }
+}
+
+module.exports = { SsmBuilder };
+