@friggframework/devtools 2.0.0--canary.461.8cf93ae.0 → 2.0.0--canary.474.213c7d9.0

package/infrastructure/domains/security/kms-builder.js

@@ -11,6 +11,8 @@
  */
 
 const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+const { KmsResourceResolver } = require('./kms-resolver');
+const { createEmptyDiscoveryResult, ResourceOwnership } = require('../shared/types');
 
 class KmsBuilder extends InfrastructureBuilder {
     constructor() {
@@ -53,11 +55,14 @@ class KmsBuilder extends InfrastructureBuilder {
     }
 
     /**
-     * Build KMS infrastructure
+     * Build KMS infrastructure using ownership-based architecture
      */
     async build(appDefinition, discoveredResources) {
         console.log(`\n[${this.name}] Configuring KMS encryption...`);
 
+        // Backwards compatibility: Translate old schema to new ownership schema
+        appDefinition = this.translateLegacyConfig(appDefinition, discoveredResources);
+
         const result = {
             resources: {},
             iamStatements: [],
@@ -66,28 +71,186 @@ class KmsBuilder extends InfrastructureBuilder {
             plugins: [],
         };
 
-        // Normalize top-level managementMode
+        // Get structured discovery result
+        const discovery = discoveredResources._structured || this.convertFlatDiscoveryToStructured(discoveredResources, appDefinition);
+
+        // Use KmsResourceResolver to make ownership decisions
+        const resolver = new KmsResourceResolver();
+        const decisions = resolver.resolveAll(appDefinition, discovery);
+
+        console.log('\n  📋 Resource Ownership Decisions:');
+        console.log(`     Key: ${decisions.key.ownership} - ${decisions.key.reason}`);
+
+        // Build resources based on ownership decisions
+        await this.buildFromDecisions(decisions, appDefinition, discoveredResources, result);
+
+        // Add IAM permissions for Lambda role
+        result.iamStatements.push({
+            Effect: 'Allow',
+            Action: ['kms:GenerateDataKey', 'kms:Decrypt', 'kms:Encrypt', 'kms:DescribeKey'],
+            Resource: result.environment.KMS_KEY_ARN,
+        });
+
+        console.log(`[${this.name}] ✅ KMS configuration completed`);
+        return result;
+    }
+
+    /**
+     * Convert flat discovery to structured discovery
+     * Provides backwards compatibility for tests
+     */
+    convertFlatDiscoveryToStructured(flatDiscovery, appDefinition = {}) {
+        const discovery = createEmptyDiscoveryResult();
+
+        if (!flatDiscovery) {
+            return discovery;
+        }
+
+        // Check if resources are from CloudFormation stack
+        const isManagedIsolated = appDefinition.managementMode === 'managed' &&
+                                   (appDefinition.vpcIsolation === 'isolated' || !appDefinition.vpcIsolation);
+        const hasExistingStackResources = isManagedIsolated && flatDiscovery.defaultKmsKeyId &&
+                                         typeof flatDiscovery.defaultKmsKeyId === 'string';
+
+        if (flatDiscovery.fromCloudFormationStack || hasExistingStackResources) {
+            discovery.fromCloudFormation = true;
+            discovery.stackName = flatDiscovery.stackName || 'assumed-stack';
+
+            // Add stack-managed resources
+            let existingLogicalIds = flatDiscovery.existingLogicalIds || [];
+
+            // Infer logical IDs from physical IDs if needed
+            if (hasExistingStackResources && existingLogicalIds.length === 0) {
+                if (flatDiscovery.defaultKmsKeyId) existingLogicalIds.push('FriggKMSKey');
+            }
+
+            existingLogicalIds.forEach(logicalId => {
+                let resourceType = '';
+                let physicalId = '';
+
+                if (logicalId === 'FriggKMSKey') {
+                    resourceType = 'AWS::KMS::Key';
+                    physicalId = flatDiscovery.defaultKmsKeyId;
+                }
+
+                if (physicalId && typeof physicalId === 'string') {
+                    discovery.stackManaged.push({
+                        logicalId,
+                        physicalId,
+                        resourceType
+                    });
+                }
+            });
+        } else {
+            // Resources discovered from AWS API (external)
+            if (flatDiscovery.defaultKmsKeyId && typeof flatDiscovery.defaultKmsKeyId === 'string') {
+                discovery.external.push({
+                    physicalId: flatDiscovery.defaultKmsKeyId,
+                    resourceType: 'AWS::KMS::Key',
+                    source: 'aws-discovery'
+                });
+            }
+        }
+
+        return discovery;
+    }
+
+    /**
+     * Translate legacy configuration to ownership-based configuration
+     * Provides backwards compatibility
+     */
+    translateLegacyConfig(appDefinition, discoveredResources) {
+        // If already using ownership schema, return as-is
+        if (appDefinition.encryption?.ownership) {
+            return appDefinition;
+        }
+
+        const translated = JSON.parse(JSON.stringify(appDefinition));
+
+        // Initialize ownership sections
+        if (!translated.encryption) translated.encryption = {};
+        if (!translated.encryption.ownership) {
+            translated.encryption.ownership = {};
+        }
+
+        // Handle top-level managementMode
         const globalMode = appDefinition.managementMode || 'discover';
-        let createIfNoneFound = appDefinition.encryption.createResourceIfNoneFound;
+        const vpcIsolation = appDefinition.vpcIsolation || 'shared';
 
         if (globalMode === 'managed') {
-            // In managed mode, always create KMS if not found
-            createIfNoneFound = true;
-            if (appDefinition.encryption.createResourceIfNoneFound !== undefined) {
+            if (appDefinition.encryption?.createResourceIfNoneFound !== undefined) {
                 console.log(`  ⚠️  managementMode='managed' ignoring: encryption.createResourceIfNoneFound`);
             }
+
+            if (vpcIsolation === 'isolated') {
+                const hasStackKms = discoveredResources?.defaultKmsKeyId &&
+                    typeof discoveredResources.defaultKmsKeyId === 'string';
+
+                if (hasStackKms) {
+                    translated.encryption.ownership.key = 'auto';
+                    console.log(`  managementMode='managed' + vpcIsolation='isolated' → stack has KMS, reusing`);
+                } else {
+                    translated.encryption.ownership.key = 'stack';
+                    console.log(`  managementMode='managed' + vpcIsolation='isolated' → no stack KMS, creating new`);
+                }
+            } else {
+                translated.encryption.ownership.key = 'auto';
+                console.log(`  managementMode='managed' + vpcIsolation='shared' → discovering KMS`);
+            }
+        } else {
+            // Handle legacy createResourceIfNoneFound
+            const createIfNoneFound = appDefinition.encryption?.createResourceIfNoneFound;
+            if (createIfNoneFound === true) {
+                translated.encryption.ownership.key = 'stack';
+            } else if (createIfNoneFound === false || createIfNoneFound === undefined) {
+                // When createResourceIfNoneFound is false or not specified:
+                // - If KMS found → use it (auto)
+                // - If not found → use environment variable (external)
+                // We use 'auto' here; the resolver will decide based on discovery
+                // But we need special handling in buildFromDecisions for the env var fallback
+                translated.encryption.ownership.key = 'auto';
+                translated.encryption._useEnvVarFallback = true;  // Flag for env var fallback
+            }
         }
 
-        // Check if we should create a new KMS key
-        if (!discoveredResources.defaultKmsKeyId && createIfNoneFound === true) {
-            console.log('  Creating new KMS key...');
+        return translated;
+    }
+
+    /**
+     * Build all KMS resources based on ownership decisions
+     */
+    async buildFromDecisions(decisions, appDefinition, discoveredResources, result) {
+        // Check for environment variable fallback flag (legacy behavior)
+        const useEnvVarFallback = appDefinition.encryption?._useEnvVarFallback;
+
+        if (decisions.key.ownership === ResourceOwnership.STACK && decisions.key.physicalId) {
+            // Key exists in stack - add definitions (CloudFormation idempotency)
+            console.log('  → Adding KMS definitions to template (existing in stack)');
             result.resources = this.createKmsKey(appDefinition);
             result.environment.KMS_KEY_ARN = { 'Fn::GetAtt': ['FriggKMSKey', 'Arn'] };
             console.log('  ✅ KMS key resources created');
-        } else {
+        } else if (decisions.key.ownership === ResourceOwnership.STACK && !decisions.key.physicalId && !useEnvVarFallback) {
+            // Create new KMS key (only if not using env var fallback)
+            console.log('  → Creating new KMS key in stack');
+            result.resources = this.createKmsKey(appDefinition);
+            result.environment.KMS_KEY_ARN = { 'Fn::GetAtt': ['FriggKMSKey', 'Arn'] };
+            console.log('  ✅ KMS key resources created');
+        } else if (decisions.key.ownership === ResourceOwnership.STACK && !decisions.key.physicalId && useEnvVarFallback) {
+            // Legacy behavior: fallback to environment variable when createResourceIfNoneFound=false/undefined
+            const createIfNoneFound = discoveredResources.defaultKmsKeyId ? true : appDefinition.encryption?.createResourceIfNoneFound;
+            const formatAsArn = createIfNoneFound === undefined;  // Format as ARN when not specified
+
+            if (formatAsArn) {
+                console.log('  → Using environment variable for KMS key (formatted as ARN)');
+                result.environment.KMS_KEY_ARN = 'arn:aws:kms:${self:provider.region}:${aws:accountId}:key/${env:AWS_DISCOVERY_KMS_KEY_ID}';
+            } else {
+                console.log('  → Using environment variable for KMS key');
+                result.environment.KMS_KEY_ARN = '${env:AWS_DISCOVERY_KMS_KEY_ID}';
+            }
+        } else if (decisions.key.ownership === ResourceOwnership.EXTERNAL) {
             // Use discovered KMS key
-            const kmsKeyId = discoveredResources.defaultKmsKeyId || '${env:AWS_DISCOVERY_KMS_KEY_ID}';
-            console.log(`  Using ${discoveredResources.defaultKmsKeyId ? 'discovered' : 'environment variable'} KMS key`);
+            const kmsKeyId = decisions.key.physicalId || '${env:AWS_DISCOVERY_KMS_KEY_ID}';
+            console.log(`  → Using ${decisions.key.physicalId ? 'discovered' : 'environment variable'} KMS key`);
 
             // Format as ARN if it's just a key ID (for IAM policies)
             const kmsArn = kmsKeyId.startsWith('arn:')
@@ -95,17 +258,11 @@ class KmsBuilder extends InfrastructureBuilder {
                 : `arn:aws:kms:\${self:provider.region}:\${aws:accountId}:key/${kmsKeyId}`;
 
             result.environment.KMS_KEY_ARN = kmsArn;
+        } else {
+            // Fallback
+            console.log('  → Using environment variable for KMS key');
+            result.environment.KMS_KEY_ARN = 'arn:aws:kms:${self:provider.region}:${aws:accountId}:key/${env:AWS_DISCOVERY_KMS_KEY_ID}';
         }
-
-        // Add IAM permissions for Lambda role
-        result.iamStatements.push({
-            Effect: 'Allow',
-            Action: ['kms:GenerateDataKey', 'kms:Decrypt', 'kms:Encrypt', 'kms:DescribeKey'],
-            Resource: result.environment.KMS_KEY_ARN,
-        });
-
-        console.log(`[${this.name}] ✅ KMS configuration completed`);
-        return result;
     }
 
     /**

package/infrastructure/domains/security/kms-resolver.js

@@ -0,0 +1,96 @@
+/**
+ * KMS (Key Management Service) Resource Resolver
+ *
+ * Resolves KMS key ownership based on user intent and discovered resources.
+ *
+ * Ownership Resolution Logic:
+ * - User sets 'stack' → Create KMS key in CloudFormation stack
+ * - User sets 'external' → Use existing KMS key (discovered or env var)
+ * - User sets 'auto' (or unspecified):
+ *   - If KMS key found in stack → Use stack resource (STACK)
+ *   - If KMS key found externally → Use external resource (EXTERNAL)
+ *   - If nothing found → Create in stack (STACK)
+ */
+
+const BaseResourceResolver = require('../shared/base-resolver');
+const { ResourceOwnership } = require('../shared/types');
+
+class KmsResourceResolver extends BaseResourceResolver {
+    constructor() {
+        super();
+    }
+
+    /**
+     * Resolve KMS key ownership
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decision with metadata
+     */
+    resolveKey(appDefinition, discovery) {
+        // Get user intent from app definition
+        const userIntent = appDefinition.encryption?.ownership?.key || ResourceOwnership.AUTO;
+
+        // Check if KMS key exists in CloudFormation stack
+        const inStack = this.isInStack('FriggKMSKey', discovery);
+
+        if (userIntent === ResourceOwnership.STACK) {
+            // Explicit: Create/manage in stack
+            const stackResource = inStack ? this.findInStack('FriggKMSKey', discovery) : null;
+            return this.createStackDecision(
+                stackResource?.physicalId || null,
+                inStack ? 'Found FriggKMSKey in CloudFormation stack' : 'Will create FriggKMSKey in stack'
+            );
+        }
+
+        if (userIntent === ResourceOwnership.EXTERNAL) {
+            // Explicit: Use external key
+            const external = this.findExternal('AWS::KMS::Key', discovery);
+            if (!external) {
+                throw new Error(
+                    'ownership.key=external but no KMS key discovered. ' +
+                    'Provide defaultKmsKeyId in discoveredResources or set ownership.key=stack'
+                );
+            }
+            return this.createExternalDecision(
+                external.physicalId,
+                'Using external KMS key per ownership.key=external'
+            );
+        }
+
+        // AUTO resolution
+        if (inStack) {
+            const stackResource = this.findInStack('FriggKMSKey', discovery);
+            return this.createStackDecision(
+                stackResource.physicalId,
+                'Found FriggKMSKey in CloudFormation stack'
+            );
+        }
+
+        // Check for external KMS key
+        const external = this.findExternal('AWS::KMS::Key', discovery);
+        if (external) {
+            return this.createExternalDecision(
+                external.physicalId,
+                'Found external KMS key via discovery'
+            );
+        }
+
+        // No KMS key found - create in stack
+        return this.createStackDecision(
+            null,
+            'No existing KMS key - will create in stack'
+        );
+    }
+
+    /**
+     * Resolve all KMS resources
+     * Convenience method for resolving all KMS resource ownership
+     */
+    resolveAll(appDefinition, discovery) {
+        return {
+            key: this.resolveKey(appDefinition, discovery),
+        };
+    }
+}
+
+module.exports = { KmsResourceResolver };

package/infrastructure/domains/security/kms-resolver.test.js

@@ -0,0 +1,216 @@
+const { KmsResourceResolver } = require('./kms-resolver');
+const { ResourceOwnership, createEmptyDiscoveryResult } = require('../shared/types');
+
+describe('KmsResourceResolver', () => {
+    let resolver;
+
+    beforeEach(() => {
+        resolver = new KmsResourceResolver();
+    });
+
+    describe('resolveKey', () => {
+        describe('Explicit ownership intent', () => {
+            it('should respect ownership.key=stack when specified', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'stack' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('Will create FriggKMSKey in stack');
+            });
+
+            it('should respect ownership.key=external when KMS key discovered', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'arn:aws:kms:us-east-1:123456789012:key/abcd-1234',
+                    resourceType: 'AWS::KMS::Key',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('arn:aws:kms:us-east-1:123456789012:key/abcd-1234');
+                expect(decision.reason).toContain('external');
+            });
+
+            it('should error when ownership.key=external but no KMS key discovered', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'external' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                expect(() => resolver.resolveKey(appDefinition, discovery))
+                    .toThrow('ownership.key=external but no KMS key discovered');
+            });
+        });
+
+        describe('Auto resolution (ownership.key=auto)', () => {
+            it('should use stack KMS key when found in CloudFormation', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.fromCloudFormation = true;
+                discovery.stackManaged.push({
+                    logicalId: 'FriggKMSKey',
+                    physicalId: 'arn:aws:kms:us-east-1:123456789012:key/stack-key',
+                    resourceType: 'AWS::KMS::Key'
+                });
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBe('arn:aws:kms:us-east-1:123456789012:key/stack-key');
+                expect(decision.reason).toContain('Found FriggKMSKey in CloudFormation stack');
+            });
+
+            it('should use external KMS key when found via discovery', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+                discovery.external.push({
+                    physicalId: 'arn:aws:kms:us-east-1:123456789012:key/external-key',
+                    resourceType: 'AWS::KMS::Key',
+                    source: 'aws-discovery'
+                });
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('arn:aws:kms:us-east-1:123456789012:key/external-key');
+                expect(decision.reason).toContain('Found external KMS key via discovery');
+            });
+
+            it('should create new KMS key when none found', () => {
+                const appDefinition = {
+                    encryption: {
+                        ownership: { key: 'auto' }
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeNull();
+                expect(decision.reason).toContain('No existing KMS key - will create in stack');
+            });
+        });
+
+        describe('Default behavior (no ownership specified)', () => {
+            it('should default to auto resolution', () => {
+                const appDefinition = {
+                    encryption: {
+                        fieldLevelEncryptionMethod: 'kms'
+                        // No ownership specified
+                    }
+                };
+                const discovery = createEmptyDiscoveryResult();
+
+                const decision = resolver.resolveKey(appDefinition, discovery);
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.reason).toContain('No existing KMS key - will create in stack');
+            });
+        });
+    });
+
+    describe('resolveAll', () => {
+        it('should return decisions for all KMS resources', () => {
+            const appDefinition = {
+                encryption: {
+                    fieldLevelEncryptionMethod: 'kms'
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+
+            const decisions = resolver.resolveAll(appDefinition, discovery);
+
+            expect(decisions).toHaveProperty('key');
+            expect(decisions.key.ownership).toBe(ResourceOwnership.STACK);
+        });
+    });
+
+    describe('Real-world scenarios', () => {
+        it('should handle managementMode=managed scenario (create KMS)', () => {
+            // In managed mode, we want to create KMS in stack
+            const appDefinition = {
+                managementMode: 'managed',
+                encryption: {
+                    fieldLevelEncryptionMethod: 'kms',
+                    ownership: { key: 'stack' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+
+            const decision = resolver.resolveKey(appDefinition, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBeNull();
+        });
+
+        it('should handle existing stack KMS key (reuse)', () => {
+            // Stack already has KMS from previous deployment
+            const appDefinition = {
+                encryption: {
+                    fieldLevelEncryptionMethod: 'kms',
+                    ownership: { key: 'auto' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+            discovery.fromCloudFormation = true;
+            discovery.stackManaged.push({
+                logicalId: 'FriggKMSKey',
+                physicalId: 'arn:aws:kms:us-east-1:123456789012:key/existing-stack-key',
+                resourceType: 'AWS::KMS::Key'
+            });
+
+            const decision = resolver.resolveKey(appDefinition, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBe('arn:aws:kms:us-east-1:123456789012:key/existing-stack-key');
+        });
+
+        it('should handle shared KMS key scenario (vpcIsolation=shared)', () => {
+            // Using shared infrastructure KMS key
+            const appDefinition = {
+                managementMode: 'managed',
+                vpcIsolation: 'shared',
+                encryption: {
+                    fieldLevelEncryptionMethod: 'kms',
+                    ownership: { key: 'auto' }
+                }
+            };
+            const discovery = createEmptyDiscoveryResult();
+            discovery.external.push({
+                physicalId: 'arn:aws:kms:us-east-1:123456789012:key/shared-key',
+                resourceType: 'AWS::KMS::Key',
+                source: 'aws-discovery'
+            });
+
+            const decision = resolver.resolveKey(appDefinition, discovery);
+
+            expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+            expect(decision.physicalId).toBe('arn:aws:kms:us-east-1:123456789012:key/shared-key');
+        });
+    });
+});