@friggframework/devtools 2.0.0-next.62 → 2.0.0-next.63

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');
+        });
+    });
+});