@friggframework/devtools 2.0.0-next.10 → 2.0.0-next.101

package/infrastructure/docs/iam-policy-templates.md

@@ -0,0 +1,193 @@
+# Frigg IAM Policy Templates
+
+This directory contains IAM policy templates for deploying Frigg applications with the appropriate permissions.
+
+## Quick Start
+
+For immediate deployment, you have two ready-to-use IAM policy options:
+
+### Option 1: Basic Policy (Recommended for getting started)
+```bash
+# Use the basic policy for core Frigg functionality
+aws iam put-user-policy \
+  --user-name frigg-deployment-user \
+  --policy-name FriggBasicDeploymentPolicy \
+  --policy-document file://domains/security/templates/iam-policy-basic.json
+```
+
+**Includes permissions for:**
+- ✅ AWS Discovery (finding your VPC, subnets, security groups)
+- ✅ CloudFormation stacks (deploy/update Frigg applications)
+- ✅ Lambda functions (create and manage serverless functions)
+- ✅ Lambda EventSourceMappings (connect Lambda to SQS, SNS, Kinesis)
+- ✅ API Gateway (HTTP endpoints for your integrations)
+- ✅ SQS/SNS (message queues and notifications)
+- ✅ S3 (deployment artifacts, including bucket tagging)
+- ✅ CloudWatch/Logs (monitoring and logging)
+- ✅ IAM roles (Lambda execution roles)
+
+### Option 2: Full Policy (All features enabled)
+```bash
+# Use the full policy for advanced Frigg features
+aws iam put-user-policy \
+  --user-name frigg-deployment-user \
+  --policy-name FriggFullDeploymentPolicy \
+  --policy-document file://domains/security/templates/iam-policy-full.json
+```
+
+**Includes everything from Basic Policy PLUS:**
+- ✅ **VPC Management** - Create route tables, NAT gateways, VPC endpoints
+- ✅ **KMS Encryption** - Field-level encryption for sensitive data
+- ✅ **SSM Parameter Store** - Secure configuration management
+
+## When to Use Which Policy
+
+### Use Basic Policy When:
+- Getting started with Frigg
+- Building simple integrations without VPC requirements
+- You want minimal AWS permissions
+- You're not handling sensitive data requiring encryption
+
+### Use Full Policy When:
+- You need VPC isolation for security/compliance
+- You're handling sensitive data requiring KMS encryption
+- You want to use SSM Parameter Store for configuration
+- You're deploying production applications
+
+## Current Issue Resolution
+
+**If you're seeing the error:** `User is not authorized to perform: ec2:CreateRouteTable`
+
+This means your current deployment user doesn't have VPC permissions. You have two options:
+
+### Quick Fix: Apply Full Policy
+```bash
+aws iam put-user-policy \
+  --user-name frigg-deployment-user \
+  --policy-name FriggFullDeploymentPolicy \
+  --policy-document file://domains/security/templates/iam-policy-full.json
+```
+
+### Alternative: Update CloudFormation Stack
+If you deployed using the CloudFormation template, update it with VPC support:
+```bash
+aws cloudformation update-stack \
+  --stack-name frigg-deployment-iam \
+  --template-body file://domains/security/templates/frigg-deployment-iam-stack.yaml \
+  --parameters ParameterKey=EnableVPCSupport,ParameterValue=true \
+  --capabilities CAPABILITY_IAM
+```
+
+## Using the IAM Generator
+
+For custom policy generation based on your app definition:
+
+```javascript
+const { generateIAMPolicy, generateIAMCloudFormation, getFeatureSummary } = require('./iam-generator');
+
+// Generate basic JSON policy
+const basicPolicy = generateIAMPolicy('basic');
+
+// Generate full JSON policy
+const fullPolicy = generateIAMPolicy('full');
+
+// Generate CloudFormation template with auto-detected features
+const summary = getFeatureSummary(appDefinition);
+const template = generateIAMCloudFormation({
+    appName: summary.appName,
+    features: summary.features,
+    userPrefix: 'frigg-deployment-user',
+    stackName: 'frigg-deployment-iam'
+});
+
+// Or manually specify features
+const customTemplate = generateIAMCloudFormation({
+    appName: 'my-app',
+    features: {
+        vpc: true,
+        kms: true,
+        ssm: true,
+        websockets: false
+    },
+    userPrefix: 'my-deployment-user',
+    stackName: 'my-deployment-stack'
+});
+```
+
+### Feature Detection
+
+Use `getFeatureSummary(appDefinition)` to automatically detect features from your app definition:
+
+```javascript
+const summary = getFeatureSummary(appDefinition);
+// Returns: { appName, features: { core, vpc, kms, ssm, websockets }, integrationCount }
+```
+
+## Security Best Practices
+
+### Resource Scoping
+Both policies are scoped to resources containing "frigg" in their names:
+- ✅ `my-frigg-app-prod` (will work)
+- ❌ `my-integration-app` (won't work - missing "frigg")
+
+### Account-Specific Resources
+Replace `*` with your AWS account ID for tighter security:
+```json
+{
+  "Resource": [
+    "arn:aws:lambda:us-east-1:123456789012:function:*frigg*"
+  ]
+}
+```
+
+### Environment-Specific Policies
+Consider separate policies for different environments:
+- `frigg-dev-policy` (full permissions for development)
+- `frigg-prod-policy` (restricted permissions for production)
+
+## Troubleshooting
+
+### Common Permission Errors
+
+1. **"ec2:CreateRouteTable" error** → Use Full Policy
+2. **"kms:GenerateDataKey" error** → Enable KMS in your policy
+3. **"ssm:GetParameter" error** → Enable SSM in your policy
+4. **Lambda VPC errors** → Ensure VPC permissions are enabled
+5. **"lambda:DeleteEventSourceMapping" error** → Update to latest policy (includes EventSourceMapping permissions)
+6. **"ec2:DeleteVpcEndpoints" error** → Update IAM policy to use `ec2:DeleteVpcEndpoints` (plural) instead of `ec2:DeleteVpcEndpoint`
+7. **"s3:PutBucketTagging" error** → Update to latest policy (includes S3 bucket tagging permissions)
+
+### Validation
+Test your policy by deploying a simple Frigg app:
+```bash
+npx create-frigg-app test-deployment
+cd test-deployment
+frigg deploy
+```
+
+### Policy Comparison
+
+| Feature | Basic Policy | Full Policy | CloudFormation Template |
+|---------|--------------|-------------|-------------------------|
+| Core Deployment | ✅ | ✅ | ✅ |
+| VPC Management | ❌ | ✅ | ✅ (conditional) |
+| KMS Encryption | ❌ | ✅ | ✅ (conditional) |
+| SSM Parameters | ❌ | ✅ | ✅ (conditional) |
+| Format | JSON | JSON | YAML with parameters |
+| Use Case | Getting started | Production ready | Infrastructure as Code |
+
+## Files in this Directory
+
+- `../domains/security/templates/iam-policy-basic.json` - Core Frigg permissions only (JSON format)
+- `../domains/security/templates/iam-policy-full.json` - All features enabled (JSON format)
+- `../domains/security/templates/frigg-deployment-iam-stack.yaml` - CloudFormation template with conditional parameters
+- `../domains/security/iam-generator.js` - Programmatic policy generation with basic/full/auto modes
+- This file (`iam-policy-templates.md`) - Quick start guide and usage examples
+
+## Support
+
+If you encounter permission issues:
+1. Check the error message for the specific missing permission
+2. Verify your resource names contain "frigg"
+3. Consider upgrading from Basic to Full policy
+4. Review the AWS-IAM-CREDENTIAL-NEEDS.md for detailed explanations

package/infrastructure/domains/admin-scripts/admin-script-builder.js

@@ -0,0 +1,330 @@
+/**
+ * Admin Script Builder
+ *
+ * Domain Layer - Hexagonal Architecture
+ *
+ * Responsible for:
+ * - Creating SQS queue for admin script execution
+ * - Creating Lambda function for script execution (worker)
+ * - Creating Lambda function for admin API routes (router)
+ * - Creating EventBridge Scheduler resources (Phase 2)
+ * - Creating IAM roles for scheduler to invoke Lambda
+ * - Granting the router/executor Lambdas IAM permission to send to the queue
+ *   and (when scheduling is enabled) manage EventBridge schedules
+ */
+
+const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+
+class AdminScriptBuilder extends InfrastructureBuilder {
+    constructor() {
+        super();
+        this.name = 'AdminScriptBuilder';
+    }
+
+    shouldExecute(appDefinition) {
+        return Array.isArray(appDefinition.adminScripts) && appDefinition.adminScripts.length > 0;
+    }
+
+    getDependencies() {
+        return []; // Can run independently
+    }
+
+    validate(appDefinition) {
+        const result = new ValidationResult();
+
+        if (!appDefinition.adminScripts) {
+            return result; // Not an error, just no scripts
+        }
+
+        if (!Array.isArray(appDefinition.adminScripts)) {
+            result.addError('adminScripts must be an array');
+            return result;
+        }
+
+        // Validate each script
+        appDefinition.adminScripts.forEach((script, index) => {
+            if (!script?.Definition?.name) {
+                result.addError(`Admin script at index ${index} is missing Definition or name`);
+            }
+        });
+
+        return result;
+    }
+
+    async build(appDefinition, discoveredResources) {
+        console.log(`\n[${this.name}] Configuring admin scripts...`);
+        console.log(`  Processing ${appDefinition.adminScripts.length} scripts...`);
+
+        const usePrismaLayer = appDefinition.usePrismaLambdaLayer !== false;
+        const adminConfig = appDefinition.admin || {};
+
+        const result = {
+            functions: {},
+            resources: {},
+            environment: {},
+            custom: {},
+            iamStatements: [],
+        };
+
+        // Create admin script queue
+        this.createAdminScriptQueue(result);
+
+        // Create Lambda function for script execution
+        this.createScriptExecutorFunction(appDefinition, result, usePrismaLayer);
+
+        // Create API routes for script management
+        this.createAdminScriptRoutes(appDefinition, result, usePrismaLayer);
+
+        // Phase 2: Create EventBridge Scheduler resources
+        if (adminConfig.enableScheduling) {
+            this.createSchedulerResources(appDefinition, result);
+        }
+
+        // Log registered scripts
+        appDefinition.adminScripts.forEach(script => {
+            const name = script.Definition?.name || 'unknown';
+            console.log(`    ✓ Registered: ${name}`);
+        });
+
+        console.log(`[${this.name}] ✅ Admin script configuration completed`);
+        return result;
+    }
+
+    createAdminScriptQueue(result) {
+        result.resources.AdminScriptQueue = {
+            Type: 'AWS::SQS::Queue',
+            Properties: {
+                QueueName: '${self:service}-${self:provider.stage}-AdminScriptQueue',
+                MessageRetentionPeriod: 86400, // 1 day
+                VisibilityTimeout: 900, // 15 minutes (Lambda max)
+                RedrivePolicy: {
+                    maxReceiveCount: 3,
+                    deadLetterTargetArn: {
+                        'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
+                    },
+                },
+            },
+        };
+
+        result.environment.ADMIN_SCRIPT_QUEUE_URL = { Ref: 'AdminScriptQueue' };
+
+        // The router enqueues async executions and scripts enqueue continuations
+        // via queueScript()/queueScriptBatch(). The base role's wildcard does not
+        // cover this queue's name, so grant SendMessage explicitly.
+        result.iamStatements.push({
+            Effect: 'Allow',
+            Action: [
+                'sqs:SendMessage',
+                'sqs:SendMessageBatch',
+                'sqs:GetQueueUrl',
+                'sqs:GetQueueAttributes',
+            ],
+            Resource: { 'Fn::GetAtt': ['AdminScriptQueue', 'Arn'] },
+        });
+
+        console.log('  ✓ Created AdminScriptQueue');
+    }
+
+    createScriptExecutorFunction(appDefinition, result, usePrismaLayer) {
+        result.functions.adminScriptExecutor = {
+            handler: 'node_modules/@friggframework/admin-scripts/src/infrastructure/script-executor-handler.handler',
+            skipEsbuild: true,
+            package: this.skipEsbuildPackageConfig(appDefinition, usePrismaLayer),
+            ...(usePrismaLayer && { layers: [{ Ref: 'PrismaLambdaLayer' }] }),
+            timeout: 900, // 15 minutes max
+            memorySize: 1024,
+            events: [
+                {
+                    sqs: {
+                        arn: { 'Fn::GetAtt': ['AdminScriptQueue', 'Arn'] },
+                        batchSize: 1,
+                    },
+                },
+            ],
+        };
+        console.log('  ✓ Created adminScriptExecutor function');
+    }
+
+    createAdminScriptRoutes(appDefinition, result, usePrismaLayer) {
+        result.functions.adminScriptRouter = {
+            handler: 'node_modules/@friggframework/admin-scripts/src/infrastructure/admin-script-router.handler',
+            skipEsbuild: true,
+            package: this.skipEsbuildPackageConfig(appDefinition, usePrismaLayer),
+            ...(usePrismaLayer && { layers: [{ Ref: 'PrismaLambdaLayer' }] }),
+            timeout: 30,
+            events: [
+                // List scripts
+                { httpApi: { path: '/admin/scripts', method: 'GET' } },
+                // Get script details
+                { httpApi: { path: '/admin/scripts/{scriptName}', method: 'GET' } },
+                // Execute script (sync or async)
+                { httpApi: { path: '/admin/scripts/{scriptName}', method: 'POST' } },
+                // Validate script input (dry-run preview)
+                { httpApi: { path: '/admin/scripts/{scriptName}/validate', method: 'POST' } },
+                // List executions for a script
+                { httpApi: { path: '/admin/scripts/{scriptName}/executions', method: 'GET' } },
+                // Get a single execution
+                {
+                    httpApi: {
+                        path: '/admin/scripts/{scriptName}/executions/{executionId}',
+                        method: 'GET',
+                    },
+                },
+                // Schedule management (Phase 2)
+                { httpApi: { path: '/admin/scripts/{scriptName}/schedule', method: 'GET' } },
+                { httpApi: { path: '/admin/scripts/{scriptName}/schedule', method: 'PUT' } },
+                { httpApi: { path: '/admin/scripts/{scriptName}/schedule', method: 'DELETE' } },
+            ],
+        };
+        console.log('  ✓ Created adminScriptRouter function');
+    }
+
+    // Without this, the skipEsbuild functions package the whole node_modules
+    // closure (aws-sdk, Prisma, dev deps) and blow past Lambda's 250 MB limit.
+    // Mirrors the exclusions the framework's other node_modules handlers use.
+    skipEsbuildPackageConfig(appDefinition, usePrismaLayer) {
+        const tlsCAFile = appDefinition?.database?.documentDB?.tlsCAFile;
+        return {
+            include: [
+                // Handlers connect to the DB, so ship the DocumentDB CA cert.
+                ...(tlsCAFile ? [tlsCAFile.replace(/^\.\//, '')] : []),
+            ],
+            exclude: [
+                'node_modules/aws-sdk/**',
+                'node_modules/@aws-sdk/**',
+                ...(usePrismaLayer
+                    ? [
+                          'node_modules/@prisma/**',
+                          'node_modules/.prisma/**',
+                          'node_modules/prisma/**',
+                          'node_modules/@friggframework/core/generated/**',
+                      ]
+                    : []),
+                'node_modules/**/node_modules/**',
+                'node_modules/@friggframework/test/**',
+                'node_modules/@friggframework/eslint-config/**',
+                'node_modules/@friggframework/prettier-config/**',
+                'node_modules/jest/**',
+                'node_modules/prettier/**',
+                'node_modules/eslint/**',
+                'node_modules/esbuild/**',
+                'node_modules/@esbuild/**',
+                'node_modules/typescript/**',
+                'node_modules/webpack/**',
+                'node_modules/osls/**',
+                'node_modules/serverless-esbuild/**',
+                'node_modules/serverless-jetpack/**',
+                'node_modules/serverless-offline/**',
+                'node_modules/serverless-offline-sqs/**',
+                'node_modules/serverless-dotenv-plugin/**',
+                'node_modules/serverless-kms-grants/**',
+                // Never deploy secrets or the lockfile.
+                '.env',
+                '.env.*',
+                '**/.env',
+                '**/.env.*',
+                '.frigg-credentials.json',
+                'package-lock.json',
+                'test/**',
+                'layers/**',
+                'coverage/**',
+                '**/*.test.js',
+                '**/*.spec.js',
+            ],
+        };
+    }
+
+    createSchedulerResources(appDefinition, result) {
+        // Constructed ARN, not Fn::GetAtt: a GetAtt edge to the executor closes a
+        // CloudFormation circular dependency via the shared Lambda execution role.
+        const executorArn = {
+            'Fn::Sub':
+                'arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:${self:service}-${self:provider.stage}-adminScriptExecutor',
+        };
+
+        // Create IAM role for EventBridge Scheduler
+        result.resources.AdminScriptSchedulerRole = {
+            Type: 'AWS::IAM::Role',
+            Properties: {
+                RoleName: '${self:service}-${self:provider.stage}-admin-script-scheduler',
+                AssumeRolePolicyDocument: {
+                    Version: '2012-10-17',
+                    Statement: [{
+                        Effect: 'Allow',
+                        Principal: { Service: 'scheduler.amazonaws.com' },
+                        Action: 'sts:AssumeRole',
+                    }],
+                },
+                Policies: [{
+                    PolicyName: 'InvokeLambda',
+                    PolicyDocument: {
+                        Version: '2012-10-17',
+                        Statement: [{
+                            Effect: 'Allow',
+                            Action: 'lambda:InvokeFunction',
+                            Resource: executorArn,
+                        }],
+                    },
+                }],
+            },
+        };
+
+        // Create schedule group
+        result.resources.AdminScriptScheduleGroup = {
+            Type: 'AWS::Scheduler::ScheduleGroup',
+            Properties: {
+                Name: '${self:service}-${self:provider.stage}-admin-scripts',
+            },
+        };
+
+        // Router-scoped, not shared provider env. Two reasons: broadcasting the
+        // resource references to every function creates CloudFormation circular
+        // deps; and SCHEDULER_PROVIDER='aws' is only valid for the admin-script
+        // adapter (the router's sole consumer) — core's scheduler factory, used
+        // by integration Lambdas, rejects 'aws', so it must not leak app-wide.
+        result.functions.adminScriptRouter.environment = {
+            ...(result.functions.adminScriptRouter.environment || {}),
+            SCHEDULER_PROVIDER: 'aws',
+            SCHEDULER_ROLE_ARN: {
+                'Fn::GetAtt': ['AdminScriptSchedulerRole', 'Arn'],
+            },
+            ADMIN_SCRIPT_SCHEDULE_GROUP: { Ref: 'AdminScriptScheduleGroup' },
+            ADMIN_SCRIPT_EXECUTOR_LAMBDA_ARN: executorArn,
+        };
+
+        // The router manages schedules through the AWS scheduler adapter, so it
+        // needs scheduler:* on this group plus iam:PassRole for the role it hands
+        // to EventBridge. (UpdateSchedule covers the upsert conflict path.)
+        result.iamStatements.push(
+            {
+                Effect: 'Allow',
+                Action: [
+                    'scheduler:CreateSchedule',
+                    'scheduler:UpdateSchedule',
+                    'scheduler:DeleteSchedule',
+                    'scheduler:GetSchedule',
+                ],
+                Resource: {
+                    'Fn::Sub': [
+                        'arn:aws:scheduler:${AWS::Region}:${AWS::AccountId}:schedule/${GroupName}/*',
+                        { GroupName: { Ref: 'AdminScriptScheduleGroup' } },
+                    ],
+                },
+            },
+            {
+                Effect: 'Allow',
+                Action: ['iam:PassRole'],
+                Resource: { 'Fn::GetAtt': ['AdminScriptSchedulerRole', 'Arn'] },
+                Condition: {
+                    StringEquals: {
+                        'iam:PassedToService': 'scheduler.amazonaws.com',
+                    },
+                },
+            }
+        );
+
+        console.log('  ✓ Created EventBridge Scheduler resources');
+    }
+}
+
+module.exports = { AdminScriptBuilder };