@friggframework/devtools 2.0.0--canary.398.53eac55.0 → 2.0.0--canary.397.878fefa.0

package/infrastructure/DEPLOYMENT-INSTRUCTIONS.md

@@ -1,268 +0,0 @@
-# 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

@@ -1,253 +0,0 @@
-# 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.