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

package/frigg-cli/__tests__/unit/commands/generate-iam.test.js

@@ -0,0 +1,97 @@
+/**
+ * Test suite for generate-iam command
+ *
+ * Drives generateIamCommand end-to-end (real getFeatureSummary +
+ * generateIAMCloudFormation) to verify appDefinition.ssm.kmsKeyArn
+ * actually reaches the generated CloudFormation template. A unit test
+ * that hand-supplies ssmKmsKeyArn straight to generateIAMCloudFormation
+ * would not catch a caller that forgets to thread it through.
+ */
+
+jest.mock('fs-extra');
+jest.mock('@friggframework/core', () => ({
+    findNearestBackendPackageJson: jest.fn()
+}));
+
+const path = require('path');
+const fs = require('fs-extra');
+const { findNearestBackendPackageJson } = require('@friggframework/core');
+const { generateIamCommand } = require('../../../generate-iam-command');
+
+describe('CLI Command: generate-iam', () => {
+    const mockBackendPath = '/mock/backend/package.json';
+    const mockBackendDir = '/mock/backend';
+    const mockAppDefinitionPath = path.join(mockBackendDir, 'index.js');
+
+    beforeEach(() => {
+        jest.resetModules();
+        jest.clearAllMocks();
+
+        jest.spyOn(process, 'exit').mockImplementation(() => {});
+        jest.spyOn(console, 'log').mockImplementation(() => {});
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+
+        findNearestBackendPackageJson.mockReturnValue(mockBackendPath);
+
+        fs.existsSync = jest.fn().mockReturnValue(true);
+        fs.ensureDir = jest.fn().mockResolvedValue();
+        fs.writeFile = jest.fn().mockResolvedValue();
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+        jest.dontMock(mockAppDefinitionPath);
+    });
+
+    it('scopes the SSM-mediated KMS grant to ssm.kmsKeyArn when configured', async () => {
+        const mockAppDefinition = {
+            name: 'test-app',
+            ssm: {
+                enable: true,
+                kmsKeyArn:
+                    'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+            }
+        };
+
+        jest.doMock(
+            mockAppDefinitionPath,
+            () => ({ Definition: mockAppDefinition }),
+            { virtual: true }
+        );
+
+        await generateIamCommand({});
+
+        expect(fs.writeFile).toHaveBeenCalled();
+        const [, generatedYaml] = fs.writeFile.mock.calls[0];
+
+        expect(generatedYaml).toContain('FriggSSMParameterKMSEncryption');
+        expect(generatedYaml).toContain(
+            'arn:aws:kms:us-east-1:123456789012:key/abcd-1234'
+        );
+        expect(generatedYaml).not.toContain(
+            'arn:aws:kms:*:${AWS::AccountId}:key/*'
+        );
+    });
+
+    it('falls back to the account-wide KMS wildcard when ssm.kmsKeyArn is not set', async () => {
+        const mockAppDefinition = {
+            name: 'test-app',
+            ssm: { enable: true }
+        };
+
+        jest.doMock(
+            mockAppDefinitionPath,
+            () => ({ Definition: mockAppDefinition }),
+            { virtual: true }
+        );
+
+        await generateIamCommand({});
+
+        expect(fs.writeFile).toHaveBeenCalled();
+        const [, generatedYaml] = fs.writeFile.mock.calls[0];
+
+        expect(generatedYaml).toContain(
+            'arn:aws:kms:*:${AWS::AccountId}:key/*'
+        );
+    });
+});

package/frigg-cli/deploy-command/index.js

@@ -267,12 +267,56 @@ async function runPostDeploymentHealthCheck(stackName, options) {
     }
 }
 
+/**
+ * Push SSM-offloaded parameters before deploying so they exist before new
+ * code cold-starts (ADR-027). A push failure aborts the deploy: shipping
+ * code whose parameters are missing would fail every cold start anyway.
+ */
+async function pushOffloadedParametersOrAbort(appDefinition, options) {
+    const {
+        getOffloadedKeys,
+    } = require('../../infrastructure/domains/parameters/offload-utils');
+    if (!appDefinition || getOffloadedKeys(appDefinition).length === 0) {
+        return;
+    }
+
+    require('dotenv').config();
+    const { pushOffloadedParameters } = require('../ssm-command');
+
+    console.log('🔒 Pushing SSM-offloaded parameters before deploy...');
+    try {
+        const { pushed } = await pushOffloadedParameters(
+            appDefinition,
+            options.stage,
+            options
+        );
+        console.log(`   ✓ ${pushed.length} parameter(s) up to date`);
+    } catch (error) {
+        console.error(`\n✗ SSM parameter push failed: ${error.message}`);
+        const pushedBeforeFailure = error.pushed || [];
+        if (pushedBeforeFailure.length === 0) {
+            console.error('   Deployment aborted — no parameters were changed.');
+        } else {
+            const names = pushedBeforeFailure.map((p) => p.name).join(', ');
+            console.error(
+                `   Deployment aborted, but ${pushedBeforeFailure.length} parameter(s) were already pushed and are now live in Parameter Store: ${names}`
+            );
+            console.error(
+                '   Those values will take effect on old Lambda code at its next SSM cache TTL refresh. Redeploy soon so the running code matches.'
+            );
+        }
+        process.exit(1);
+    }
+}
+
 async function deployCommand(options) {
     console.log('Deploying the serverless application...');
 
     const appDefinition = loadAppDefinition();
     const environment = validateAndBuildEnvironment(appDefinition, options);
 
+    await pushOffloadedParametersOrAbort(appDefinition, options);
+
     // Execute deployment
     const exitCode = await executeServerlessDeployment(environment, options);
 

package/frigg-cli/generate-command/index.js

@@ -120,7 +120,8 @@ async function generateCommand(options = {}) {
                     appName,
                     features,
                     userPrefix: options.user || 'frigg-deployment-user',
-                    stackName: options.stackName || 'frigg-deployment-iam'
+                    stackName: options.stackName || 'frigg-deployment-iam',
+                    ssmKmsKeyArn: appDefinition.ssm?.kmsKeyArn
                 });
                 fileExtension = 'yaml';
                 deploymentInstructions = generateCloudFormationInstructions(options);

package/frigg-cli/generate-iam-command.js

@@ -64,7 +64,8 @@ async function generateIamCommand(options = {}) {
             appName: summary.appName,
             features: summary.features,
             userPrefix: deploymentUserName,
-            stackName
+            stackName,
+            ssmKmsKeyArn: summary.ssmKmsKeyArn
         });
 
         // Determine output file path

package/frigg-cli/index.js

@@ -86,6 +86,7 @@ const { dbSetupCommand } = require('./db-setup-command');
 const { doctorCommand } = require('./doctor-command');
 const { repairCommand } = require('./repair-command');
 const { authCommand } = require('./auth-command');
+const { ssmPushCommand } = require('./ssm-command');
 
 const program = new Command();
 
@@ -169,6 +170,20 @@ program
     .option('-v, --verbose', 'enable verbose output')
     .action(repairCommand);
 
+// SSM command group for the parameter offload feature (ADR-027)
+const ssmProgram = program
+    .command('ssm')
+    .description('Manage SSM Parameter Store offloaded configuration');
+
+ssmProgram
+    .command('push')
+    .description('Push SSM-offloaded environment values to Parameter Store')
+    .option('-s, --stage <stage>', 'deployment stage', 'dev')
+    .option('-r, --region <region>', 'AWS region (defaults to AWS_REGION env var or us-east-1)')
+    .option('--allow-empty', 'skip (instead of fail on) keys with missing or empty values')
+    .option('--tier <tier>', 'override tier for all keys: standard (4KB values) or advanced (8KB, billed)')
+    .action(ssmPushCommand);
+
 // Auth command group for testing API module authentication
 const authProgram = program
     .command('auth')
@@ -205,4 +220,4 @@ authProgram
 
 program.parse(process.argv);
 
-module.exports = { initCommand, installCommand, startCommand, buildCommand, deployCommand, generateIamCommand, uiCommand, dbSetupCommand, doctorCommand, repairCommand, authCommand };
+module.exports = { initCommand, installCommand, startCommand, buildCommand, deployCommand, generateIamCommand, uiCommand, dbSetupCommand, doctorCommand, repairCommand, authCommand, ssmPushCommand };

package/frigg-cli/ssm-command/index.js

@@ -0,0 +1,270 @@
+/**
+ * frigg ssm push
+ *
+ * Writes SSM-offloaded environment values (see ADR-027) from the CLI
+ * process environment into Parameter Store. Runs automatically before
+ * `frigg deploy` so parameters exist before new code cold-starts; also
+ * available standalone to rotate values without deploying.
+ */
+
+const path = require('path');
+const dotenv = require('dotenv');
+const {
+    getOffloadedKeys,
+    resolveParameterPrefix,
+    validateOffloadConfig,
+} = require('../../infrastructure/domains/parameters/offload-utils');
+
+const TIER_LIMITS = {
+    standard: 4096,
+    advanced: 8192,
+};
+
+const THROTTLE_BACKOFF_MS = [100, 200, 400];
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Send a PutParameterCommand, retrying ThrottlingException with short
+ * exponential backoff (mirrors sendWithRetry in core/parameters-to-env.js).
+ */
+async function putParameterWithRetry(client, PutParameterCommand, input) {
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await client.send(new PutParameterCommand(input));
+        } catch (error) {
+            if (
+                error.name === 'ThrottlingException' &&
+                attempt < THROTTLE_BACKOFF_MS.length
+            ) {
+                await sleep(THROTTLE_BACKOFF_MS[attempt]);
+                attempt += 1;
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+
+/**
+ * Resolve the tier for a single offloaded key. An explicit `--tier` CLI
+ * option overrides every key; otherwise each key uses its own
+ * ssm.parameters[KEY].tier, defaulting to 'standard'.
+ */
+function resolveKeyTier(appDefinition, key, options = {}) {
+    const raw =
+        options.tier ||
+        appDefinition.ssm?.parameters?.[key]?.tier ||
+        'standard';
+    const tier = String(raw).toLowerCase();
+    if (!TIER_LIMITS[tier]) {
+        throw new Error(
+            `Unknown parameter tier '${raw}' for ${key}. Use 'standard' or 'advanced'.`
+        );
+    }
+    return tier;
+}
+
+/**
+ * Build the PutParameter specs for every offloaded key, reading values
+ * from process.env. Throws on invalid config, missing values (unless
+ * allowEmpty), or values that exceed their own tier limit.
+ */
+function collectParameterSpecs(appDefinition, stage, options = {}) {
+    const { errors: configErrors } = validateOffloadConfig(appDefinition);
+    if (configErrors.length > 0) {
+        throw new Error(
+            `Invalid SSM offload configuration:\n  - ${configErrors.join(
+                '\n  - '
+            )}`
+        );
+    }
+
+    const keys = getOffloadedKeys(appDefinition);
+    if (keys.length === 0) {
+        return { specs: [], skipped: [] };
+    }
+
+    const prefix = resolveParameterPrefix(appDefinition, stage);
+    const specs = [];
+    const skipped = [];
+    const missing = [];
+    const oversized = [];
+
+    for (const key of keys) {
+        const value = process.env[key];
+
+        if (value === undefined || value === '') {
+            if (options.allowEmpty) {
+                skipped.push(key);
+            } else {
+                missing.push(key);
+            }
+            continue;
+        }
+
+        const tier = resolveKeyTier(appDefinition, key, options);
+        const maxBytes = TIER_LIMITS[tier];
+        const bytes = Buffer.byteLength(value, 'utf8');
+        if (bytes > maxBytes) {
+            oversized.push(
+                `${key} (${bytes} bytes > ${tier} tier limit ${maxBytes})`
+            );
+            continue;
+        }
+
+        specs.push({
+            key,
+            name: `${prefix}/${key}`,
+            value,
+            type: appDefinition.ssm?.parameters?.[key]?.type || 'String',
+            tier,
+        });
+    }
+
+    if (missing.length > 0) {
+        throw new Error(
+            `Missing or empty values for offloaded keys: ${missing.join(
+                ', '
+            )}. Set them in the environment (or .env) before pushing, or pass --allow-empty to skip them.`
+        );
+    }
+
+    if (oversized.length > 0) {
+        throw new Error(
+            `Offloaded values exceed their parameter tier limit: ${oversized.join(
+                ', '
+            )}. Values over ${TIER_LIMITS.standard} bytes need the advanced tier (up to ${TIER_LIMITS.advanced} bytes, billed by AWS): set ssm.parameters.<KEY>.tier: 'advanced' in the app definition, or pass --tier advanced to 'frigg ssm push'.`
+        );
+    }
+
+    return { specs, skipped };
+}
+
+/**
+ * Resolve the region parameters are pushed to. An explicit `--region`
+ * option wins; otherwise fall back to AWS_REGION and finally to the same
+ * default the composed stack uses ('us-east-1'), so pushes and cold-start
+ * reads always target the same region.
+ */
+function resolvePushRegion(options = {}) {
+    return options.region || process.env.AWS_REGION || 'us-east-1';
+}
+
+/**
+ * Push all offloaded parameters for an app definition. Silent no-op when
+ * the offload set is empty. Returns { pushed, skipped }.
+ */
+async function pushOffloadedParameters(appDefinition, stage, options = {}) {
+    const { specs, skipped } = collectParameterSpecs(
+        appDefinition,
+        stage,
+        options
+    );
+
+    for (const key of skipped) {
+        console.warn(
+            `⚠️  Skipping ${key}: no value in the environment (--allow-empty)`
+        );
+    }
+
+    if (specs.length === 0) {
+        return { pushed: [], skipped };
+    }
+
+    const { SSMClient, PutParameterCommand } = require('@aws-sdk/client-ssm');
+    const client = new SSMClient({
+        region: resolvePushRegion(options),
+    });
+
+    const pushed = [];
+    for (const spec of specs) {
+        const input = {
+            Name: spec.name,
+            Value: spec.value,
+            Type: spec.type,
+            Overwrite: true,
+        };
+        if (spec.tier === 'advanced') {
+            input.Tier = 'Advanced';
+        }
+        if (spec.type === 'SecureString' && appDefinition.ssm?.kmsKeyArn) {
+            input.KeyId = appDefinition.ssm.kmsKeyArn;
+        }
+
+        try {
+            const result = await putParameterWithRetry(
+                client,
+                PutParameterCommand,
+                input
+            );
+            pushed.push({ name: spec.name, version: result.Version });
+            console.log(
+                `   ✅ ${spec.name} (${spec.type}, v${result.Version})`
+            );
+        } catch (error) {
+            const failure = new Error(
+                `Failed to push parameter ${spec.name} (${spec.key}): ${error.message}`
+            );
+            failure.pushed = pushed;
+            throw failure;
+        }
+    }
+
+    return { pushed, skipped };
+}
+
+function loadAppDefinition() {
+    const appDefPath = path.join(process.cwd(), 'index.js');
+    const { Definition } = require(appDefPath);
+    return Definition;
+}
+
+/**
+ * `frigg ssm push` command action.
+ */
+async function ssmPushCommand(options) {
+    dotenv.config();
+
+    let appDefinition;
+    try {
+        appDefinition = loadAppDefinition();
+    } catch (error) {
+        console.error(
+            `✗ Could not load the app definition from ${process.cwd()}/index.js: ${error.message}`
+        );
+        process.exit(1);
+    }
+
+    const keys = getOffloadedKeys(appDefinition);
+    if (keys.length === 0) {
+        console.log(
+            'No environment variables are marked for SSM offload — nothing to push.'
+        );
+        return;
+    }
+
+    console.log(
+        `🔒 Pushing ${keys.length} offloaded parameter(s) for stage '${options.stage}'...`
+    );
+
+    try {
+        const { pushed } = await pushOffloadedParameters(
+            appDefinition,
+            options.stage,
+            options
+        );
+        console.log(`✓ Pushed ${pushed.length} parameter(s)`);
+    } catch (error) {
+        console.error(`✗ ${error.message}`);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    ssmPushCommand,
+    pushOffloadedParameters,
+    collectParameterSpecs,
+    resolvePushRegion,
+};