@friggframework/devtools 2.0.0-next.44 → 2.0.0-next.46

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

package/infrastructure/domains/shared/base-builder.js

@@ -0,0 +1,112 @@
+/**
+ * Base Infrastructure Builder Interface
+ * 
+ * Domain Layer - Hexagonal Architecture
+ * 
+ * This abstract class defines the contract for all infrastructure builders.
+ * Each infrastructure domain (VPC, KMS, Database, etc.) implements this interface.
+ * 
+ * Benefits of Hexagonal Architecture:
+ * - Domain logic separated from infrastructure concerns
+ * - Easy to test in isolation
+ * - Dependency injection for cross-cutting concerns
+ * - Clear boundaries between domains
+ * - Enables parallel execution where dependencies allow
+ */
+
+class InfrastructureBuilder {
+    /**
+     * Build infrastructure resources
+     * 
+     * @param {Object} appDefinition - Application definition from user
+     * @param {Object} discoveredResources - Resources discovered from AWS
+     * @returns {Object} CloudFormation resources to add to template
+     * @throws {Error} If validation fails or build encounters errors
+     */
+    async build(appDefinition, discoveredResources) {
+        throw new Error('InfrastructureBuilder.build() must be implemented by subclass');
+    }
+
+    /**
+     * Validate configuration before building
+     * 
+     * @param {Object} config - Configuration to validate
+     * @returns {Object} Validation result { valid: boolean, errors: string[] }
+     */
+    validate(config) {
+        throw new Error('InfrastructureBuilder.validate() must be implemented by subclass');
+    }
+
+    /**
+     * Check if this builder should execute
+     * 
+     * @param {Object} appDefinition - Application definition
+     * @returns {boolean} True if builder should execute
+     */
+    shouldExecute(appDefinition) {
+        return false;
+    }
+
+    /**
+     * Get dependencies (other builders that must execute first)
+     * 
+     * @returns {Array<string>} Array of builder names this depends on
+     */
+    getDependencies() {
+        return [];
+    }
+
+    /**
+     * Get builder name for logging and dependency resolution
+     * 
+     * @returns {string} Builder name
+     */
+    getName() {
+        return this.constructor.name;
+    }
+}
+
+/**
+ * Value Object for validation results
+ */
+class ValidationResult {
+    constructor(valid = true, errors = [], warnings = []) {
+        this.valid = valid;
+        this.errors = errors;
+        this.warnings = warnings;
+    }
+
+    addError(error) {
+        this.errors.push(error);
+        this.valid = false;
+    }
+
+    addWarning(warning) {
+        this.warnings.push(warning);
+    }
+
+    hasErrors() {
+        return this.errors.length > 0;
+    }
+
+    hasWarnings() {
+        return this.warnings.length > 0;
+    }
+
+    toString() {
+        let result = `Valid: ${this.valid}\n`;
+        if (this.errors.length > 0) {
+            result += `Errors:\n  - ${this.errors.join('\n  - ')}\n`;
+        }
+        if (this.warnings.length > 0) {
+            result += `Warnings:\n  - ${this.warnings.join('\n  - ')}\n`;
+        }
+        return result;
+    }
+}
+
+module.exports = {
+    InfrastructureBuilder,
+    ValidationResult,
+};
+

package/infrastructure/domains/shared/base-resolver.js

@@ -0,0 +1,186 @@
+/**
+ * Base Resource Resolver
+ *
+ * Abstract base class for resource ownership resolution.
+ * Each builder has its own resolver (VpcResolver, AuroraResolver, etc.)
+ * that extends this base class.
+ *
+ * Resolver Layer - Hexagonal Architecture
+ */
+
+const {
+    ResourceOwnership,
+    resolveOwnership,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack
+} = require('./types');
+
+class BaseResourceResolver {
+    /**
+     * Find resource in CloudFormation stack
+     * @protected
+     * @param {string} logicalId - Logical resource ID
+     * @param {Object} discovery - Discovery result
+     * @returns {Object|null} Stack resource or null
+     */
+    findInStack(logicalId, discovery) {
+        return findStackResource(discovery, logicalId);
+    }
+
+    /**
+     * Find external resource by type
+     * @protected
+     * @param {string} resourceType - CloudFormation resource type
+     * @param {Object} discovery - Discovery result
+     * @returns {Object|null} External resource or null
+     */
+    findExternal(resourceType, discovery) {
+        return findExternalResource(discovery, resourceType);
+    }
+
+    /**
+     * Find all external resources by type
+     * @protected
+     * @param {Object} discovery - Discovery result
+     * @param {string} resourceType - CloudFormation resource type
+     * @returns {Object[]} Array of external resources
+     */
+    findAllExternalResources(discovery, resourceType) {
+        return findAllExternalResources(discovery, resourceType);
+    }
+
+    /**
+     * Check if resource is in stack
+     * @protected
+     * @param {string} logicalId - Logical resource ID
+     * @param {Object} discovery - Discovery result
+     * @returns {boolean}
+     */
+    isInStack(logicalId, discovery) {
+        return isResourceInStack(discovery, logicalId);
+    }
+
+    /**
+     * Validate that external resource IDs are provided when required
+     * @protected
+     * @param {*} resourceIds - Resource IDs to validate
+     * @param {string} resourceName - Name for error message
+     * @throws {Error} If resourceIds is not provided
+     */
+    requireExternalIds(resourceIds, resourceName) {
+        if (!resourceIds || (Array.isArray(resourceIds) && resourceIds.length === 0)) {
+            throw new Error(
+                `ownership='external' for ${resourceName} requires external.${resourceName} to be provided in app definition`
+            );
+        }
+    }
+
+    /**
+     * Resolve ownership for a resource
+     * @protected
+     * @param {string} userIntent - User's ownership intent ('stack' | 'external' | 'auto')
+     * @param {string} logicalId - CloudFormation logical ID
+     * @param {string} resourceType - CloudFormation resource type
+     * @param {Object} discovery - Discovery result
+     * @returns {Object} Resource decision
+     */
+    resolveResourceOwnership(userIntent, logicalId, resourceType, discovery) {
+        // Use helper to work with both old flat structure and new structured
+        const structured = discovery._structured || discovery;
+
+        const inStack = this.isInStack(logicalId, structured);
+        const externalResource = this.findExternal(resourceType, structured);
+
+        const ownership = resolveOwnership(
+            userIntent || ResourceOwnership.AUTO,
+            inStack,
+            externalResource !== null
+        );
+
+        const stackResource = inStack ? this.findInStack(logicalId, structured) : null;
+
+        return {
+            ownership,
+            physicalId: stackResource?.physicalId || externalResource?.physicalId,
+            reason: this._buildReasonString(ownership, inStack, externalResource, userIntent),
+            metadata: {
+                logicalId,
+                resourceType,
+                userIntent: userIntent || 'auto',
+                inStack,
+                foundExternal: externalResource !== null
+            }
+        };
+    }
+
+    /**
+     * Build human-readable reason string
+     * @private
+     */
+    _buildReasonString(ownership, inStack, externalResource, userIntent) {
+        if (userIntent === 'stack') {
+            return 'User explicitly specified ownership=stack';
+        }
+
+        if (userIntent === 'external') {
+            return 'User explicitly specified ownership=external';
+        }
+
+        // Auto-decided
+        if (ownership === ResourceOwnership.STACK) {
+            if (inStack) {
+                return 'Found in CloudFormation stack (must keep in template to avoid deletion)';
+            }
+            return 'No existing resource found - will create in stack';
+        }
+
+        if (ownership === ResourceOwnership.EXTERNAL) {
+            return 'Found external resource via discovery';
+        }
+
+        return 'Ownership resolved via auto-detection';
+    }
+
+    /**
+     * Create a resource decision for explicit external reference
+     * @protected
+     * @param {string|string[]} physicalIds - Physical resource ID(s)
+     * @param {string} reason - Reason string
+     * @returns {Object} Resource decision
+     */
+    createExternalDecision(physicalIds, reason = 'Using external resource reference') {
+        const ids = Array.isArray(physicalIds) ? physicalIds : [physicalIds];
+
+        return {
+            ownership: ResourceOwnership.EXTERNAL,
+            physicalId: ids[0],
+            physicalIds: ids,
+            reason,
+            metadata: {
+                source: 'user-provided'
+            }
+        };
+    }
+
+    /**
+     * Create a resource decision for stack-managed resource
+     * @protected
+     * @param {string} [physicalId] - Physical ID if resource already exists
+     * @param {string} reason - Reason string
+     * @returns {Object} Resource decision
+     */
+    createStackDecision(physicalId = null, reason = 'Managed by CloudFormation stack') {
+        return {
+            ownership: ResourceOwnership.STACK,
+            physicalId,
+            reason,
+            metadata: {
+                source: physicalId ? 'discovered' : 'new'
+            }
+        };
+    }
+}
+
+module.exports = BaseResourceResolver;