@friggframework/devtools 2.0.0-next.3 → 2.0.0-next.31

package/infrastructure/DEPLOYMENT-INSTRUCTIONS.md

@@ -0,0 +1,268 @@
+# Frigg IAM Deployment Instructions
+
+This guide explains how to deploy the IAM CloudFormation stack to create the necessary AWS credentials for your Frigg deployment pipeline.
+
+## Prerequisites
+
+- AWS CLI installed and configured with administrator privileges
+- AWS account ID
+- Appropriate permissions to create IAM resources
+
+## Deployment Steps
+
+You can deploy the stack using either the AWS Management Console (UI) or AWS CLI.
+
+### Option A: Deploy via AWS Management Console (UI)
+
+#### 1. Upload and Create Stack
+
+1. Log in to the [AWS Management Console](https://console.aws.amazon.com/)
+2. Navigate to **CloudFormation** service
+3. Click **Create stack** → **With new resources (standard)**
+4. In the **Specify template** section:
+   - Select **Upload a template file**
+   - Click **Choose file** and select `frigg-deployment-iam-stack.yaml`
+   - Click **Next**
+
+#### 2. Configure Stack Details
+
+1. **Stack name**: Enter `frigg-deployment-iam`
+2. **Parameters**:
+   - **DeploymentUserName**: `frigg-deployment-user` (or customize)
+   - **EnableVPCSupport**: `true`
+   - **EnableKMSSupport**: `true`
+   - **EnableSSMSupport**: `true`
+3. Click **Next**
+
+#### 3. Configure Stack Options
+
+1. Leave all options as default (or configure tags if needed)
+2. Click **Next**
+
+#### 4. Review and Create
+
+1. Review all settings
+2. **Important**: Check the box that says **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**
+3. Click **Submit**
+4. Wait for the stack to reach **CREATE_COMPLETE** status (usually 2-3 minutes)
+
+#### 5. Retrieve Credentials from Console
+
+1. Once the stack is created, click on the stack name
+2. Go to the **Outputs** tab
+3. Note the **AccessKeyId** value
+4. To get the Secret Access Key:
+   - Click on the **Resources** tab
+   - Find **FriggDeploymentCredentials** and click on its Physical ID link
+   - This will take you to AWS Secrets Manager
+   - Click **Retrieve secret value**
+   - Copy the **SecretAccessKey** value
+
+### Option B: Deploy via AWS CLI
+
+#### 1. Deploy the CloudFormation Stack
+
+```bash
+aws cloudformation deploy \
+  --template-file frigg-deployment-iam-stack.yaml \
+  --stack-name frigg-deployment-iam \
+  --capabilities CAPABILITY_NAMED_IAM \
+  --parameter-overrides \
+    DeploymentUserName=frigg-deployment-user \
+    EnableVPCSupport=true \
+    EnableKMSSupport=true \
+    EnableSSMSupport=true
+```
+
+#### 2. Retrieve Deployment Credentials
+
+After successful deployment, retrieve the credentials:
+
+```bash
+# Get the Access Key ID
+aws cloudformation describe-stacks \
+  --stack-name frigg-deployment-iam \
+  --query 'Stacks[0].Outputs[?OutputKey==`AccessKeyId`].OutputValue' \
+  --output text
+
+# Get the Secret Access Key from Secrets Manager
+aws secretsmanager get-secret-value \
+  --secret-id frigg-deployment-credentials \
+  --query SecretString \
+  --output text | jq -r .SecretAccessKey
+```
+
+### 3. Configure CI/CD Environment
+
+#### GitHub Actions
+
+Add these secrets to your GitHub repository:
+
+1. Go to Settings → Secrets and variables → Actions
+2. Add new repository secrets:
+   - `AWS_ACCESS_KEY_ID`: The Access Key ID from step 2
+   - `AWS_SECRET_ACCESS_KEY`: The Secret Access Key from step 2
+
+Example GitHub Actions workflow:
+
+```yaml
+name: Deploy Frigg Application
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v2
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-1
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Deploy Frigg application
+        run: npx frigg deploy
+```
+
+#### GitLab CI/CD
+
+Add variables in Settings → CI/CD → Variables:
+
+```yaml
+deploy:
+  image: node:18
+  before_script:
+    - npm install
+  script:
+    - export AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
+    - export AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
+    - export AWS_REGION=us-east-1
+    - npx frigg deploy
+  only:
+    - main
+```
+
+#### Jenkins
+
+Store credentials in Jenkins Credentials Manager and use in pipeline:
+
+```groovy
+pipeline {
+    agent any
+    environment {
+        AWS_ACCESS_KEY_ID = credentials('frigg-aws-access-key-id')
+        AWS_SECRET_ACCESS_KEY = credentials('frigg-aws-secret-access-key')
+        AWS_REGION = 'us-east-1'
+    }
+    stages {
+        stage('Deploy') {
+            steps {
+                sh 'npm install'
+                sh 'npx frigg deploy'
+            }
+        }
+    }
+}
+```
+
+### 4. Local Development Setup
+
+For local development, configure AWS CLI profile:
+
+```bash
+# Option 1: Use AWS CLI configure
+aws configure --profile frigg-deployment
+# Enter the Access Key ID and Secret Access Key when prompted
+
+# Option 2: Add to ~/.aws/credentials manually
+[frigg-deployment]
+aws_access_key_id = YOUR_ACCESS_KEY_ID
+aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
+```
+
+Use the profile in your deployment:
+
+```bash
+export AWS_PROFILE=frigg-deployment
+npx frigg deploy
+```
+
+## Stack Parameters
+
+- **DeploymentUserName**: Name of the IAM user (default: `frigg-deployment-user`)
+- **EnableVPCSupport**: Enable VPC-related permissions (default: `true`)
+- **EnableKMSSupport**: Enable KMS encryption permissions (default: `true`)
+- **EnableSSMSupport**: Enable SSM Parameter Store permissions (default: `true`)
+
+## Security Best Practices
+
+1. **Rotate Credentials Regularly**: Create a new access key periodically and update your CI/CD systems
+2. **Use Separate Stacks**: Deploy separate stacks for dev, staging, and production environments
+3. **Enable MFA**: For production deployments, consider using IAM roles with MFA requirements
+4. **Audit Access**: Regularly review CloudTrail logs for deployment activities
+
+## Updating the Stack
+
+To update permissions or parameters:
+
+```bash
+aws cloudformation update-stack \
+  --stack-name frigg-deployment-iam \
+  --template-body file://frigg-deployment-iam-stack.yaml \
+  --capabilities CAPABILITY_NAMED_IAM \
+  --parameter-overrides \
+    EnableVPCSupport=false  # Example: disable VPC support
+```
+
+## Deleting the Stack
+
+⚠️ **Warning**: This will delete the IAM user and all associated access keys!
+
+```bash
+# First, delete any access keys manually
+aws iam delete-access-key \
+  --user-name frigg-deployment-user \
+  --access-key-id YOUR_ACCESS_KEY_ID
+
+# Then delete the stack
+aws cloudformation delete-stack --stack-name frigg-deployment-iam
+```
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+If you encounter permission errors during deployment:
+
+1. Check that the IAM user name follows the pattern `*frigg*`
+2. Ensure your resources (Lambda functions, stacks) include "frigg" in their names
+3. Verify the correct AWS region is configured
+
+### Discovery Failures
+
+If AWS resource discovery fails during build:
+
+1. Verify the deployment user has the discovery permissions
+2. Check that default VPC and subnets exist in your region
+3. Review build logs for specific error messages
+
+### Stack Creation Failures
+
+Common issues:
+
+- **CAPABILITY_NAMED_IAM required**: Add `--capabilities CAPABILITY_NAMED_IAM` to deploy command
+- **User already exists**: Choose a different `DeploymentUserName` parameter
+- **Policy limit exceeded**: AWS accounts have limits on managed policies; consider consolidating
+
+## Additional Resources
+
+- [AWS IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html)
+- [Frigg Documentation](https://github.com/friggframework/frigg)
+- [AWS CloudFormation Documentation](https://docs.aws.amazon.com/cloudformation/)

package/infrastructure/GENERATE-IAM-DOCS.md

@@ -0,0 +1,253 @@
+# Generate IAM Command
+
+The `frigg generate-iam` command creates a customized IAM CloudFormation template based on your specific Frigg application configuration.
+
+## Overview
+
+Instead of using a generic IAM policy that includes all possible permissions, this command analyzes your AppDefinition and generates an IAM stack that only includes the permissions your application actually needs.
+
+## Usage
+
+```bash
+npx frigg generate-iam [options]
+```
+
+### Options
+
+- `-o, --output <path>` - Output directory (default: `backend/infrastructure`)
+- `-u, --user <name>` - Deployment user name (default: `frigg-deployment-user`)
+- `-s, --stack-name <name>` - CloudFormation stack name (default: `frigg-deployment-iam`)
+- `-v, --verbose` - Enable verbose output
+
+### Examples
+
+```bash
+# Generate with defaults
+npx frigg generate-iam
+
+# Specify custom output directory
+npx frigg generate-iam --output ./aws-infrastructure
+
+# Custom user name and stack name
+npx frigg generate-iam --user my-app-deployer --stack-name my-app-iam
+
+# Verbose output
+npx frigg generate-iam --verbose
+```
+
+## What Gets Generated
+
+The command analyzes your `backend/index.js` AppDefinition and generates IAM policies based on:
+
+### Always Included (Core Features)
+- **CloudFormation** - Stack management permissions
+- **Lambda** - Function deployment and management
+- **IAM** - Role creation and management for Lambda functions
+- **S3** - Deployment bucket access
+- **SQS/SNS** - Messaging services
+- **CloudWatch/Logs** - Monitoring and logging
+- **API Gateway** - REST API management
+
+### Conditionally Included (Based on AppDefinition)
+
+#### VPC Support (`vpc.enable: true`)
+- VPC endpoint creation and management
+- NAT Gateway creation and management
+- Route table and security group management
+- Elastic IP allocation
+
+#### KMS Encryption (`encryption.useDefaultKMSForFieldLevelEncryption: true`)
+- KMS key usage for Lambda and S3
+- Data encryption and decryption permissions
+
+#### SSM Parameter Store (`ssm.enable: true`)
+- Parameter retrieval permissions
+- Scoped to parameters containing "frigg" in the path
+
+#### WebSocket Support (`websockets.enable: true`)
+- Currently included in core permissions
+- API Gateway WebSocket management
+
+## Sample AppDefinition Analysis
+
+Given this AppDefinition:
+
+```javascript
+const appDefinition = {
+    name: 'my-integration-app',
+    integrations: [AsanaIntegration, SlackIntegration],
+    vpc: {
+        enable: true
+    },
+    encryption: {
+        useDefaultKMSForFieldLevelEncryption: true
+    },
+    ssm: {
+        enable: false
+    },
+    websockets: {
+        enable: true
+    }
+};
+```
+
+The command will generate:
+- ✅ Core deployment permissions
+- ✅ VPC management permissions
+- ✅ KMS encryption permissions  
+- ❌ SSM Parameter Store permissions (disabled)
+- ✅ WebSocket permissions (via core)
+
+## Generated File Structure
+
+The command creates:
+
+```
+backend/infrastructure/
+├── frigg-deployment-iam.yaml    # Main CloudFormation template
+```
+
+## Security Benefits
+
+### Principle of Least Privilege
+- Only includes permissions your app actually uses
+- Scoped resource patterns (e.g., only resources containing "frigg")
+- No unnecessary cloud service permissions
+
+### Resource Scoping
+All permissions are scoped to resources following naming patterns:
+- `*frigg*` - General Frigg resources
+- `*serverless*` - Deployment buckets
+- `internal-error-queue-*` - Error handling queues
+
+### Conditional Policies
+Feature-specific policies are only created when:
+- The feature is enabled in your AppDefinition
+- CloudFormation conditions control policy attachment
+
+## Deployment Workflow
+
+After generating the template:
+
+### 1. Deploy the Stack
+```bash
+aws cloudformation deploy \
+  --template-file backend/infrastructure/frigg-deployment-iam.yaml \
+  --stack-name frigg-deployment-iam \
+  --capabilities CAPABILITY_NAMED_IAM \
+  --parameter-overrides DeploymentUserName=frigg-deployment-user
+```
+
+### 2. Retrieve Access Key
+```bash
+aws cloudformation describe-stacks \
+  --stack-name frigg-deployment-iam \
+  --query 'Stacks[0].Outputs[?OutputKey==`AccessKeyId`].OutputValue' \
+  --output text
+```
+
+### 3. Get Secret Access Key
+```bash
+aws secretsmanager get-secret-value \
+  --secret-id frigg-deployment-credentials \
+  --query SecretString \
+  --output text | jq -r .SecretAccessKey
+```
+
+### 4. Configure CI/CD
+Add the credentials to your deployment environment:
+- GitHub Actions: Repository secrets
+- GitLab CI: Environment variables
+- Jenkins: Credentials manager
+- Local: AWS credentials file
+
+## Troubleshooting
+
+### Command Not Found
+```bash
+# Install dependencies
+npm install
+
+# Ensure you're in a Frigg project
+ls backend/index.js
+```
+
+### No AppDefinition Found
+- Ensure `backend/index.js` exports a `Definition` object
+- Check that the Definition follows the correct structure
+
+### Permission Errors During Deployment
+- Ensure your AWS CLI is configured with admin permissions
+- Add `--capabilities CAPABILITY_NAMED_IAM` to deployment commands
+
+### Generated Policy Too Restrictive
+- Check that your resources follow naming conventions (contain "frigg")
+- Enable additional features in your AppDefinition if needed
+- Review the generated template for resource patterns
+
+## Comparison with Generic Template
+
+| Aspect | Generic Template | Generated Template |
+|--------|-----------------|-------------------|
+| Size | ~15KB | ~8-12KB (varies) |
+| Permissions | All features | Only enabled features |
+| Security | Broad access | Scoped access |
+| Maintenance | Manual updates | Auto-generated |
+| Deployment Risk | Over-privileged | Least privilege |
+
+## Integration with Development Workflow
+
+### Local Development
+1. Update AppDefinition
+2. Run `npx frigg generate-iam`
+3. Deploy updated IAM stack
+4. Test deployment with new permissions
+
+### CI/CD Pipeline
+```yaml
+# GitHub Actions example
+- name: Generate IAM Template
+  run: npx frigg generate-iam
+
+- name: Deploy IAM Stack
+  run: |
+    aws cloudformation deploy \
+      --template-file backend/infrastructure/frigg-deployment-iam.yaml \
+      --stack-name ${{ env.STACK_NAME }} \
+      --capabilities CAPABILITY_NAMED_IAM
+```
+
+### Version Control
+- Commit generated templates to version control
+- Review changes in pull requests
+- Track permission changes over time
+
+## Best Practices
+
+1. **Regenerate After Changes** - Run the command whenever you modify your AppDefinition
+2. **Review Generated Templates** - Check the generated YAML before deployment
+3. **Test Deployments** - Verify your app can deploy with the generated permissions
+4. **Environment Separation** - Use different stack names for dev/staging/prod
+5. **Regular Audits** - Periodically review and minimize permissions
+
+## Advanced Usage
+
+### Custom Parameter Values
+```bash
+# Enable all features regardless of AppDefinition
+npx frigg generate-iam --verbose
+
+# Then manually edit the generated template to set:
+# EnableVPCSupport: true
+# EnableKMSSupport: true  
+# EnableSSMSupport: true
+```
+
+### Multiple Environments
+```bash
+# Generate for different environments
+npx frigg generate-iam --stack-name my-app-dev-iam --output ./aws/dev
+npx frigg generate-iam --stack-name my-app-prod-iam --output ./aws/prod
+```
+
+This command helps you maintain secure, minimal IAM policies that evolve with your application requirements.

package/infrastructure/IAM-POLICY-TEMPLATES.md

@@ -0,0 +1,176 @@
+# 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://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://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://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://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 } = require('./iam-generator');
+
+// Generate basic JSON policy
+const basicPolicy = generateIAMPolicy('basic');
+
+// Generate full JSON policy  
+const fullPolicy = generateIAMPolicy('full');
+
+// Generate CloudFormation template with auto-detection
+const autoTemplate = generateIAMCloudFormation(appDefinition, { mode: 'auto' });
+
+// Generate CloudFormation template with specific mode
+const basicTemplate = generateIAMCloudFormation(appDefinition, { mode: 'basic' });
+const fullTemplate = generateIAMCloudFormation(appDefinition, { mode: 'full' });
+```
+
+### Generator Modes
+
+- **`basic`** - Core permissions only, ignores app definition features
+- **`full`** - All features enabled, ignores app definition features  
+- **`auto`** - Analyzes app definition and enables features as needed (default)
+
+## 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
+
+- `iam-policy-basic.json` - Core Frigg permissions only (JSON format)
+- `iam-policy-full.json` - All features enabled (JSON format)
+- `frigg-deployment-iam-stack.yaml` - CloudFormation template with conditional parameters
+- `iam-generator.js` - Programmatic policy generation with basic/full/auto modes
+- `AWS-IAM-CREDENTIAL-NEEDS.md` - Detailed permission explanations and troubleshooting
+- `IAM-POLICY-TEMPLATES.md` - This file - 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