@friggframework/devtools 2.0.0--canary.398.e2147f7.0 → 2.0.0--canary.398.c9e5d61.0

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/WEBSOCKET-CONFIGURATION.md

@@ -0,0 +1,105 @@
+# WebSocket Configuration for Frigg Applications
+
+## Overview
+
+WebSockets in Frigg applications are now **disabled by default** and can be enabled through the AppDefinition configuration. This allows applications that don't need real-time communication to avoid deploying unnecessary WebSocket infrastructure.
+
+## Enabling WebSockets
+
+To enable WebSocket support in your Frigg application, add the `websockets` configuration to your AppDefinition:
+
+```javascript
+// backend/index.js
+const appDefinition = {
+    integrations: [YourIntegration],
+    websockets: {
+        enable: true  // Enable WebSocket support
+    },
+    // ... other configuration
+};
+
+module.exports = {
+    Definition: appDefinition,
+};
+```
+
+## What Happens When WebSockets Are Enabled
+
+When you set `websockets.enable: true`, the following resources are deployed:
+
+1. **WebSocket API Gateway** - AWS API Gateway WebSocket endpoint
+2. **Lambda Functions** - Handlers for `$connect`, `$disconnect`, and `$default` routes
+3. **Database Collection** - MongoDB collection to store active WebSocket connections
+4. **Environment Variable** - `WEBSOCKET_API_ENDPOINT` is automatically configured
+
+## Using WebSockets in Your Application
+
+Once enabled, you can use the `WebsocketConnection` model to send messages to connected clients:
+
+```javascript
+const { WebsocketConnection } = require('@friggframework/core');
+
+// Get all active connections and send a message
+const connections = await WebsocketConnection.getActiveConnections();
+for (const connection of connections) {
+    await connection.send({
+        type: 'update',
+        data: { message: 'Hello from server!' }
+    });
+}
+```
+
+## Default Behavior (WebSockets Disabled)
+
+When websockets are disabled (the default):
+- No WebSocket infrastructure is deployed
+- `WebsocketConnection.getActiveConnections()` returns an empty array
+- No `WEBSOCKET_API_ENDPOINT` environment variable is set
+- No additional Lambda functions or API Gateway resources are created
+
+## Use Cases for WebSockets
+
+Enable WebSockets when you need:
+- Real-time updates for integration sync status
+- Live streaming of data processing progress
+- Push notifications to connected clients
+- Real-time collaboration features
+
+## Cost Considerations
+
+Disabling WebSockets by default helps reduce costs by:
+- Avoiding API Gateway WebSocket charges when not needed
+- Reducing Lambda function invocations
+- Eliminating unnecessary database operations for connection management
+
+## Migration Guide
+
+If you have an existing Frigg application that uses WebSockets:
+
+1. Add the websockets configuration to your AppDefinition:
+   ```javascript
+   websockets: {
+       enable: true
+   }
+   ```
+
+2. Redeploy your application:
+   ```bash
+   npx frigg deploy
+   ```
+
+Your WebSocket functionality will continue to work as before.
+
+## Troubleshooting
+
+### WebSocket Connection Errors
+If you see errors related to WebSocket connections, ensure:
+1. WebSockets are enabled in your AppDefinition
+2. The application has been redeployed after enabling WebSockets
+3. The `WEBSOCKET_API_ENDPOINT` environment variable is set (automatically done during deployment)
+
+### WebsocketConnection.getActiveConnections() Returns Empty Array
+This is expected behavior when:
+- WebSockets are disabled (default)
+- No clients are currently connected
+- The `WEBSOCKET_API_ENDPOINT` environment variable is not set

package/infrastructure/aws-discovery.js

@@ -1,6 +1,24 @@
-const { EC2Client, DescribeVpcsCommand, DescribeSubnetsCommand, DescribeSecurityGroupsCommand, DescribeRouteTablesCommand } = require('@aws-sdk/client-ec2');
-const { KMSClient, ListKeysCommand, DescribeKeyCommand } = require('@aws-sdk/client-kms');
-const { STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts');
+let EC2Client, DescribeVpcsCommand, DescribeSubnetsCommand, DescribeSecurityGroupsCommand, DescribeRouteTablesCommand;
+let KMSClient, ListKeysCommand, DescribeKeyCommand;
+let STSClient, GetCallerIdentityCommand;
+
+function loadEC2() {
+    if (!EC2Client) {
+        ({ EC2Client, DescribeVpcsCommand, DescribeSubnetsCommand, DescribeSecurityGroupsCommand, DescribeRouteTablesCommand } = require('@aws-sdk/client-ec2'));
+    }
+}
+
+function loadKMS() {
+    if (!KMSClient) {
+        ({ KMSClient, ListKeysCommand, DescribeKeyCommand } = require('@aws-sdk/client-kms'));
+    }
+}
+
+function loadSTS() {
+    if (!STSClient) {
+        ({ STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts'));
+    }
+}
 
 /**
  * AWS Resource Discovery utilities for Frigg applications
@@ -13,6 +31,9 @@ class AWSDiscovery {
      */
     constructor(region = 'us-east-1') {
         this.region = region;
+        loadEC2();
+        loadKMS();
+        loadSTS();
         this.ec2Client = new EC2Client({ region });
         this.kmsClient = new KMSClient({ region });
         this.stsClient = new STSClient({ region });

package/infrastructure/build-time-discovery.js

@@ -1,6 +1,12 @@
 const fs = require('fs');
 const path = require('path');
-const { AWSDiscovery } = require('./aws-discovery');
+let AWSDiscovery;
+
+function loadAWSDiscovery() {
+    if (!AWSDiscovery) {
+        ({ AWSDiscovery } = require('./aws-discovery'));
+    }
+}
 
 /**
  * Build-time AWS resource discovery and configuration injection
@@ -13,6 +19,7 @@ class BuildTimeDiscovery {
      * @param {string} [region=process.env.AWS_REGION || 'us-east-1'] - AWS region for discovery
      */
     constructor(region = process.env.AWS_REGION || 'us-east-1') {
+        loadAWSDiscovery();
         this.region = region;
         this.discovery = new AWSDiscovery(region);
     }
@@ -140,6 +147,7 @@ class BuildTimeDiscovery {
             }
             
             // Create discovery instance with specified region
+            loadAWSDiscovery();
             const discovery = new AWSDiscovery(region);
             const resources = await discovery.discoverResources();
             
@@ -149,6 +157,7 @@ class BuildTimeDiscovery {
                 AWS_DISCOVERY_SECURITY_GROUP_ID: resources.defaultSecurityGroupId,
                 AWS_DISCOVERY_SUBNET_ID_1: resources.privateSubnetId1,
                 AWS_DISCOVERY_SUBNET_ID_2: resources.privateSubnetId2,
+                AWS_DISCOVERY_PUBLIC_SUBNET_ID: resources.publicSubnetId,
                 AWS_DISCOVERY_ROUTE_TABLE_ID: resources.privateRouteTableId,
                 AWS_DISCOVERY_KMS_KEY_ID: resources.defaultKmsKeyId
             };