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

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

@@ -0,0 +1,308 @@
+/**
+ * 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
+    );
+
+    if (specs.length === 0 && skipped.length === 0) {
+        return { pushed: [], skipped };
+    }
+
+    const {
+        SSMClient,
+        PutParameterCommand,
+        GetParametersCommand,
+    } = require('@aws-sdk/client-ssm');
+    const client = new SSMClient({
+        region: resolvePushRegion(options),
+    });
+
+    // --allow-empty only rotates keys that already exist. A skipped key still
+    // ships in FRIGG_SSM_OFFLOADED_KEYS, so if its parameter does not exist the
+    // runtime fails fast at cold start on every function — a green deploy that
+    // bricks the fleet. Verify existence and abort instead.
+    if (skipped.length > 0) {
+        const prefix = resolveParameterPrefix(appDefinition, stage);
+        const names = skipped.map((key) => `${prefix}/${key}`);
+        const existing = new Set();
+        for (let i = 0; i < names.length; i += 10) {
+            const { Parameters = [] } = await client.send(
+                new GetParametersCommand({ Names: names.slice(i, i + 10) })
+            );
+            for (const param of Parameters) {
+                existing.add(param.Name);
+            }
+        }
+        const orphaned = skipped.filter(
+            (key) => !existing.has(`${prefix}/${key}`)
+        );
+        if (orphaned.length > 0) {
+            throw new Error(
+                `--allow-empty skipped ${orphaned.join(
+                    ', '
+                )}, but no such parameter exists in Parameter Store. --allow-empty ` +
+                    `only rotates keys that already have a value; a skipped key with no ` +
+                    `parameter stays in FRIGG_SSM_OFFLOADED_KEYS and fails every function ` +
+                    `at cold start. Set a value and push without --allow-empty.`
+            );
+        }
+        for (const key of skipped) {
+            console.warn(
+                `⚠️  Skipping ${key}: no value in the environment; keeping the existing Parameter Store value (--allow-empty)`
+            );
+        }
+    }
+
+    if (specs.length === 0) {
+        return { pushed: [], skipped };
+    }
+
+    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,
+};

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

@@ -0,0 +1,318 @@
+const { mockClient } = require('aws-sdk-client-mock');
+const {
+    SSMClient,
+    PutParameterCommand,
+    GetParametersCommand,
+} = require('@aws-sdk/client-ssm');
+const { pushOffloadedParameters, resolvePushRegion } = require('./index');
+
+describe('ssm-command pushOffloadedParameters', () => {
+    let ssmMock;
+    const originalEnv = process.env;
+
+    const appDefinition = {
+        name: 'my-app',
+        ssm: {
+            enable: true,
+            parameters: {
+                MY_SECRET: { type: 'SecureString' },
+            },
+        },
+        environment: {
+            MY_CONFIG: 'ssm',
+            PLAIN: true,
+        },
+    };
+
+    beforeEach(() => {
+        ssmMock = mockClient(SSMClient);
+        ssmMock.on(PutParameterCommand).resolves({ Version: 1 });
+        process.env = {
+            ...originalEnv,
+            MY_SECRET: 'shh',
+            MY_CONFIG: 'value-1',
+        };
+    });
+
+    afterEach(() => {
+        ssmMock.restore();
+        process.env = originalEnv;
+    });
+
+    it('pushes each offloaded key with resolved name, type, and overwrite', async () => {
+        const result = await pushOffloadedParameters(appDefinition, 'prod');
+
+        const calls = ssmMock.commandCalls(PutParameterCommand);
+        expect(calls).toHaveLength(2);
+
+        const byName = Object.fromEntries(
+            calls.map((c) => [c.args[0].input.Name, c.args[0].input])
+        );
+        expect(byName['/frigg/my-app/prod/MY_SECRET']).toMatchObject({
+            Value: 'shh',
+            Type: 'SecureString',
+            Overwrite: true,
+        });
+        expect(byName['/frigg/my-app/prod/MY_CONFIG']).toMatchObject({
+            Value: 'value-1',
+            Type: 'String',
+            Overwrite: true,
+        });
+        expect(result.pushed).toHaveLength(2);
+    });
+
+    it('passes KeyId for SecureString when ssm.kmsKeyArn is set', async () => {
+        const withKey = {
+            ...appDefinition,
+            ssm: {
+                ...appDefinition.ssm,
+                kmsKeyArn: 'arn:aws:kms:us-east-1:1:key/k',
+            },
+        };
+        await pushOffloadedParameters(withKey, 'dev');
+
+        const inputs = ssmMock
+            .commandCalls(PutParameterCommand)
+            .map((c) => c.args[0].input);
+        const secure = inputs.find((i) => i.Type === 'SecureString');
+        const plain = inputs.find((i) => i.Type === 'String');
+        expect(secure.KeyId).toBe('arn:aws:kms:us-east-1:1:key/k');
+        expect(plain.KeyId).toBeUndefined();
+    });
+
+    it('is a silent no-op when nothing is offloaded', async () => {
+        const result = await pushOffloadedParameters(
+            { name: 'x', environment: { PLAIN: true } },
+            'dev'
+        );
+        expect(result.pushed).toHaveLength(0);
+        expect(ssmMock.commandCalls(PutParameterCommand)).toHaveLength(0);
+    });
+
+    it('throws listing keys with missing or empty values', async () => {
+        delete process.env.MY_SECRET;
+        process.env.MY_CONFIG = '';
+
+        await expect(
+            pushOffloadedParameters(appDefinition, 'dev')
+        ).rejects.toThrow(/MY_SECRET.*MY_CONFIG|MY_CONFIG.*MY_SECRET/s);
+        expect(ssmMock.commandCalls(PutParameterCommand)).toHaveLength(0);
+    });
+
+    it('skips missing values with allowEmpty when the parameter already exists', async () => {
+        delete process.env.MY_SECRET;
+        ssmMock.on(GetParametersCommand).resolves({
+            Parameters: [{ Name: '/frigg/my-app/dev/MY_SECRET' }],
+        });
+
+        const result = await pushOffloadedParameters(appDefinition, 'dev', {
+            allowEmpty: true,
+        });
+        expect(result.skipped).toEqual(['MY_SECRET']);
+        expect(ssmMock.commandCalls(PutParameterCommand)).toHaveLength(1);
+    });
+
+    it('aborts when allowEmpty skips a key that does not exist in Parameter Store', async () => {
+        delete process.env.MY_SECRET;
+        ssmMock.on(GetParametersCommand).resolves({ Parameters: [] });
+
+        await expect(
+            pushOffloadedParameters(appDefinition, 'dev', { allowEmpty: true })
+        ).rejects.toThrow(/MY_SECRET.*no such parameter|--allow-empty/s);
+        expect(ssmMock.commandCalls(PutParameterCommand)).toHaveLength(0);
+    });
+
+    it('rejects values over the standard tier limit and suggests advanced', async () => {
+        process.env.MY_CONFIG = 'x'.repeat(4097);
+
+        await expect(
+            pushOffloadedParameters(appDefinition, 'dev')
+        ).rejects.toThrow(/advanced/i);
+    });
+
+    it('accepts large values with the advanced tier', async () => {
+        process.env.MY_CONFIG = 'x'.repeat(4097);
+
+        await pushOffloadedParameters(appDefinition, 'dev', {
+            tier: 'advanced',
+        });
+        const inputs = ssmMock
+            .commandCalls(PutParameterCommand)
+            .map((c) => c.args[0].input);
+        expect(
+            inputs.find((i) => i.Name.endsWith('/MY_CONFIG')).Tier
+        ).toBe('Advanced');
+    });
+
+    it('rejects values over the advanced tier limit', async () => {
+        process.env.MY_CONFIG = 'x'.repeat(8193);
+
+        await expect(
+            pushOffloadedParameters(appDefinition, 'dev', {
+                tier: 'advanced',
+            })
+        ).rejects.toThrow(/8192|8 ?KB/i);
+    });
+
+    describe('per-key tier resolution', () => {
+        const withKeyTier = {
+            ...appDefinition,
+            ssm: {
+                ...appDefinition.ssm,
+                parameters: {
+                    MY_SECRET: { type: 'SecureString' },
+                    MY_CONFIG: { tier: 'advanced' },
+                },
+            },
+        };
+
+        it('accepts a large value when the key is configured advanced in the app definition', async () => {
+            process.env.MY_CONFIG = 'x'.repeat(4097);
+
+            await pushOffloadedParameters(withKeyTier, 'dev');
+
+            const config = ssmMock
+                .commandCalls(PutParameterCommand)
+                .map((c) => c.args[0].input)
+                .find((i) => i.Name.endsWith('/MY_CONFIG'));
+            expect(config.Tier).toBe('Advanced');
+        });
+
+        it('validates each key against its own configured tier', async () => {
+            // MY_CONFIG (advanced) tolerates 5000 bytes; MY_SECRET (standard) does not
+            process.env.MY_CONFIG = 'x'.repeat(5000);
+            process.env.MY_SECRET = 'y'.repeat(5000);
+
+            await expect(
+                pushOffloadedParameters(withKeyTier, 'dev')
+            ).rejects.toThrow(/MY_SECRET/);
+            expect(ssmMock.commandCalls(PutParameterCommand)).toHaveLength(0);
+        });
+
+        it('does not tag standard-tier keys with an Advanced tier', async () => {
+            await pushOffloadedParameters(withKeyTier, 'dev');
+
+            const secret = ssmMock
+                .commandCalls(PutParameterCommand)
+                .map((c) => c.args[0].input)
+                .find((i) => i.Name.endsWith('/MY_SECRET'));
+            expect(secret.Tier).toBeUndefined();
+        });
+
+        it('lets the --tier CLI option override per-key config for all keys', async () => {
+            process.env.MY_CONFIG = 'x'.repeat(4097);
+
+            await expect(
+                pushOffloadedParameters(withKeyTier, 'dev', {
+                    tier: 'standard',
+                })
+            ).rejects.toThrow(/advanced/i);
+        });
+    });
+
+    it('throws on invalid offload config (markers without ssm.enable)', async () => {
+        await expect(
+            pushOffloadedParameters(
+                { name: 'x', environment: { FOO: 'ssm' } },
+                'dev'
+            )
+        ).rejects.toThrow(/ssm\.enable/);
+    });
+
+    it('wraps AWS errors with the parameter name', async () => {
+        ssmMock
+            .on(PutParameterCommand, {
+                Name: '/frigg/my-app/dev/MY_SECRET',
+            })
+            .rejects(new Error('boom'));
+
+        await expect(
+            pushOffloadedParameters(appDefinition, 'dev')
+        ).rejects.toThrow(/MY_SECRET/);
+    });
+
+    it('retries a throttled PutParameter and succeeds', async () => {
+        const throttle = Object.assign(new Error('Rate exceeded'), {
+            name: 'ThrottlingException',
+        });
+        ssmMock
+            .on(PutParameterCommand, {
+                Name: '/frigg/my-app/dev/MY_SECRET',
+            })
+            .rejectsOnce(throttle)
+            .resolves({ Version: 2 });
+
+        const result = await pushOffloadedParameters(appDefinition, 'dev');
+
+        expect(result.pushed).toHaveLength(2);
+        const secretCalls = ssmMock
+            .commandCalls(PutParameterCommand)
+            .filter(
+                (c) => c.args[0].input.Name === '/frigg/my-app/dev/MY_SECRET'
+            );
+        expect(secretCalls).toHaveLength(2);
+    });
+
+    it('exposes keys pushed so far on a mid-batch failure', async () => {
+        // MY_CONFIG (sorted before MY_SECRET) succeeds; MY_SECRET fails.
+        ssmMock
+            .on(PutParameterCommand, {
+                Name: '/frigg/my-app/dev/MY_CONFIG',
+            })
+            .resolves({ Version: 1 });
+        ssmMock
+            .on(PutParameterCommand, {
+                Name: '/frigg/my-app/dev/MY_SECRET',
+            })
+            .rejects(new Error('boom'));
+
+        let caught;
+        try {
+            await pushOffloadedParameters(appDefinition, 'dev');
+        } catch (error) {
+            caught = error;
+        }
+
+        expect(caught).toBeDefined();
+        expect(caught.pushed).toEqual([
+            { name: '/frigg/my-app/dev/MY_CONFIG', version: 1 },
+        ]);
+    });
+
+    it('honors a custom parameterPrefix', async () => {
+        const custom = {
+            ...appDefinition,
+            ssm: { ...appDefinition.ssm, parameterPrefix: '/team/x' },
+        };
+        await pushOffloadedParameters(custom, 'dev');
+
+        const names = ssmMock
+            .commandCalls(PutParameterCommand)
+            .map((c) => c.args[0].input.Name);
+        expect(names).toEqual(
+            expect.arrayContaining([
+                '/team/x/MY_SECRET',
+                '/team/x/MY_CONFIG',
+            ])
+        );
+    });
+
+    describe('resolvePushRegion', () => {
+        it('prefers an explicit --region option over the environment', () => {
+            process.env.AWS_REGION = 'us-west-2';
+            expect(resolvePushRegion({ region: 'eu-central-1' })).toBe(
+                'eu-central-1'
+            );
+        });
+
+        it('falls back to AWS_REGION when no option is given', () => {
+            process.env.AWS_REGION = 'us-west-2';
+            expect(resolvePushRegion({})).toBe('us-west-2');
+        });
+
+        it('defaults to us-east-1 when neither option nor AWS_REGION is set', () => {
+            delete process.env.AWS_REGION;
+            expect(resolvePushRegion({})).toBe('us-east-1');
+        });
+    });
+});