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

package/infrastructure/AWS-IAM-CREDENTIAL-NEEDS.md

@@ -1,561 +0,0 @@
-# AWS IAM Credential Requirements for Frigg Applications
-
-This document outlines the minimum AWS IAM permissions required to build and deploy Frigg applications with VPC, KMS, and SSM support.
-
-## Overview
-
-Frigg applications require two distinct sets of permissions:
-
-1. **Discovery-Time Permissions** - Used during the build process to discover default AWS resources
-2. **Deployment-Time Permissions** - Used during actual deployment to create CloudFormation resources
-
-The AWS discovery process runs during the `before:package:initialize` serverless hook to automatically find your default VPC, subnets, security groups, and KMS keys, eliminating the need for manual resource ID lookup.
-
-## Discovery-Time Permissions (Build Process)
-
-These permissions are required when `aws-discovery.js` runs during the build to find your default AWS resources:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "AWSDiscoveryPermissions",
-      "Effect": "Allow",
-      "Action": [
-        "sts:GetCallerIdentity",
-        "ec2:DescribeVpcs",
-        "ec2:DescribeSubnets", 
-        "ec2:DescribeSecurityGroups",
-        "ec2:DescribeRouteTables",
-        "kms:ListKeys",
-        "kms:DescribeKey"
-      ],
-      "Resource": "*"
-    }
-  ]
-}
-```
-
-### What Each Permission Does:
-- **`sts:GetCallerIdentity`** - Gets your AWS account ID for KMS key ARN construction
-- **`ec2:DescribeVpcs`** - Finds your default VPC or first available VPC
-- **`ec2:DescribeSubnets`** - Identifies private subnets within your VPC
-- **`ec2:DescribeSecurityGroups`** - Locates default security group or Frigg-specific security group
-- **`ec2:DescribeRouteTables`** - Determines which subnets are private (no direct internet gateway route)
-- **`kms:ListKeys`** - Lists available KMS keys in your account
-- **`kms:DescribeKey`** - Gets details about KMS keys to find customer-managed keys
-
-## Core Deployment Permissions
-
-Required for basic Frigg application deployment:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "CloudFormationFriggStacks",
-      "Effect": "Allow",
-      "Action": [
-        "cloudformation:CreateStack",
-        "cloudformation:UpdateStack",
-        "cloudformation:DeleteStack",
-        "cloudformation:DescribeStacks",
-        "cloudformation:DescribeStackEvents",
-        "cloudformation:DescribeStackResources",
-        "cloudformation:DescribeStackResource",
-        "cloudformation:ListStackResources",
-        "cloudformation:GetTemplate",
-        "cloudformation:ValidateTemplate",
-        "cloudformation:DescribeChangeSet",
-        "cloudformation:CreateChangeSet",
-        "cloudformation:DeleteChangeSet",
-        "cloudformation:ExecuteChangeSet"
-      ],
-      "Resource": [
-        "arn:aws:cloudformation:*:*:stack/*frigg*/*"
-      ]
-    },
-    {
-      "Sid": "S3DeploymentBucket",
-      "Effect": "Allow", 
-      "Action": [
-        "s3:CreateBucket",
-        "s3:PutObject",
-        "s3:GetObject",
-        "s3:DeleteObject",
-        "s3:PutBucketPolicy",
-        "s3:PutBucketVersioning",
-        "s3:PutBucketPublicAccessBlock",
-        "s3:GetBucketLocation",
-        "s3:ListBucket"
-      ],
-      "Resource": [
-        "arn:aws:s3:::*serverless*",
-        "arn:aws:s3:::*serverless*/*"
-      ]
-    },
-    {
-      "Sid": "LambdaFriggFunctions",
-      "Effect": "Allow",
-      "Action": [
-        "lambda:CreateFunction",
-        "lambda:UpdateFunctionCode",
-        "lambda:UpdateFunctionConfiguration",
-        "lambda:DeleteFunction",
-        "lambda:GetFunction",
-        "lambda:ListFunctions",
-        "lambda:PublishVersion",
-        "lambda:CreateAlias",
-        "lambda:UpdateAlias",
-        "lambda:DeleteAlias",
-        "lambda:GetAlias",
-        "lambda:AddPermission",
-        "lambda:RemovePermission",
-        "lambda:GetPolicy",
-        "lambda:PutProvisionedConcurrencyConfig",
-        "lambda:DeleteProvisionedConcurrencyConfig",
-        "lambda:PutConcurrency",
-        "lambda:DeleteConcurrency",
-        "lambda:TagResource",
-        "lambda:UntagResource",
-        "lambda:ListVersionsByFunction"
-      ],
-      "Resource": [
-        "arn:aws:lambda:*:*:function:*frigg*"
-      ]
-    },
-    {
-      "Sid": "IAMRolesForFriggLambda",
-      "Effect": "Allow",
-      "Action": [
-        "iam:CreateRole",
-        "iam:DeleteRole", 
-        "iam:GetRole",
-        "iam:PassRole",
-        "iam:PutRolePolicy",
-        "iam:DeleteRolePolicy",
-        "iam:GetRolePolicy",
-        "iam:AttachRolePolicy",
-        "iam:DetachRolePolicy",
-        "iam:TagRole",
-        "iam:UntagRole"
-      ],
-      "Resource": [
-        "arn:aws:iam::*:role/*frigg*",
-        "arn:aws:iam::*:role/*frigg*LambdaRole*"
-      ]
-    },
-    {
-      "Sid": "IAMPolicyVersionPermissions",
-      "Effect": "Allow",
-      "Action": [
-        "iam:ListPolicyVersions"
-      ],
-      "Resource": [
-        "arn:aws:iam::*:policy/*"
-      ]
-    },
-    {
-      "Sid": "FriggMessagingServices",
-      "Effect": "Allow",
-      "Action": [
-        "sqs:CreateQueue",
-        "sqs:DeleteQueue",
-        "sqs:GetQueueAttributes",
-        "sqs:SetQueueAttributes",
-        "sqs:GetQueueUrl",
-        "sqs:TagQueue",
-        "sqs:UntagQueue"
-      ],
-      "Resource": [
-        "arn:aws:sqs:*:*:*frigg*",
-        "arn:aws:sqs:*:*:internal-error-queue-*"
-      ]
-    },
-    {
-      "Sid": "FriggSNSTopics",
-      "Effect": "Allow",
-      "Action": [
-        "sns:CreateTopic",
-        "sns:DeleteTopic", 
-        "sns:GetTopicAttributes",
-        "sns:SetTopicAttributes",
-        "sns:Subscribe",
-        "sns:Unsubscribe",
-        "sns:TagResource",
-        "sns:UntagResource"
-      ],
-      "Resource": [
-        "arn:aws:sns:*:*:*frigg*"
-      ]
-    },
-    {
-      "Sid": "FriggMonitoringAndLogs",
-      "Effect": "Allow",
-      "Action": [
-        "cloudwatch:PutMetricAlarm",
-        "cloudwatch:DeleteAlarms",
-        "cloudwatch:DescribeAlarms",
-        "logs:CreateLogGroup",
-        "logs:CreateLogStream",
-        "logs:DeleteLogGroup",
-        "logs:DescribeLogGroups",
-        "logs:DescribeLogStreams",
-        "logs:FilterLogEvents",
-        "logs:PutLogEvents",
-        "logs:PutRetentionPolicy"
-      ],
-      "Resource": [
-        "arn:aws:logs:*:*:log-group:/aws/lambda/*frigg*",
-        "arn:aws:logs:*:*:log-group:/aws/lambda/*frigg*:*",
-        "arn:aws:cloudwatch:*:*:alarm:*frigg*"
-      ]
-    },
-    {
-      "Sid": "FriggAPIGateway",
-      "Effect": "Allow", 
-      "Action": [
-        "apigateway:POST",
-        "apigateway:PUT",
-        "apigateway:DELETE",
-        "apigateway:GET",
-        "apigateway:PATCH"
-      ],
-      "Resource": [
-        "arn:aws:apigateway:*::/restapis",
-        "arn:aws:apigateway:*::/restapis/*",
-        "arn:aws:apigateway:*::/domainnames",
-        "arn:aws:apigateway:*::/domainnames/*"
-      ]
-    }
-  ]
-}
-```
-
-## Feature-Specific Permissions
-
-### VPC Support
-
-Additional permissions needed when your app definition includes `vpc: { enable: true }`:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "FriggVPCEndpointManagement",
-      "Effect": "Allow",
-      "Action": [
-        "ec2:CreateVpcEndpoint",
-        "ec2:DeleteVpcEndpoint", 
-        "ec2:DescribeVpcEndpoints",
-        "ec2:ModifyVpcEndpoint",
-        "ec2:CreateNatGateway",
-        "ec2:DeleteNatGateway",
-        "ec2:DescribeNatGateways",
-        "ec2:AllocateAddress",
-        "ec2:ReleaseAddress",
-        "ec2:DescribeAddresses",
-        "ec2:CreateRouteTable",
-        "ec2:DeleteRouteTable",
-        "ec2:DescribeRouteTables",
-        "ec2:CreateRoute",
-        "ec2:DeleteRoute",
-        "ec2:AssociateRouteTable",
-        "ec2:DisassociateRouteTable",
-        "ec2:CreateSecurityGroup",
-        "ec2:DeleteSecurityGroup",
-        "ec2:AuthorizeSecurityGroupEgress",
-        "ec2:AuthorizeSecurityGroupIngress",
-        "ec2:RevokeSecurityGroupEgress",
-        "ec2:RevokeSecurityGroupIngress"
-      ],
-      "Resource": "*",
-      "Condition": {
-        "StringLike": {
-          "ec2:CreateAction": [
-            "CreateVpcEndpoint",
-            "CreateNatGateway", 
-            "CreateRouteTable",
-            "CreateRoute",
-            "CreateSecurityGroup"
-          ]
-        }
-      }
-    }
-  ]
-}
-```
-
-**What this enables:**
-- Creates NAT Gateway for Lambda internet access to external APIs (Salesforce, HubSpot, etc.)
-- Creates VPC endpoints for AWS services (S3, DynamoDB, KMS, SSM) to reduce NAT Gateway costs
-- Creates route tables and subnet associations for proper Lambda networking
-- Automatically configures your Lambda functions to run in your default VPC with full internet access
-
-### KMS Support
-
-Additional permissions needed when your app definition includes `encryption: { useDefaultKMSForFieldLevelEncryption: true }`:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "FriggKMSEncryptionRuntime",
-      "Effect": "Allow",
-      "Action": [
-        "kms:GenerateDataKey",
-        "kms:Decrypt"
-      ],
-      "Resource": [
-        "arn:aws:kms:*:*:key/*"
-      ],
-      "Condition": {
-        "StringEquals": {
-          "kms:ViaService": [
-            "lambda.*.amazonaws.com",
-            "s3.*.amazonaws.com"
-          ]
-        }
-      }
-    }
-  ]
-}
-```
-
-**What this enables:**
-- Lambda functions can encrypt and decrypt data using your default KMS key
-- Automatic discovery and configuration of customer-managed KMS keys
-- Fallback to AWS-managed keys if no customer keys are available
-
-### SSM Parameter Store Support
-
-Additional permissions needed when your app definition includes `ssm: { enable: true }`:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "FriggSSMParameterAccess",
-      "Effect": "Allow", 
-      "Action": [
-        "ssm:GetParameter",
-        "ssm:GetParameters",
-        "ssm:GetParametersByPath"
-      ],
-      "Resource": [
-        "arn:aws:ssm:*:*:parameter/*frigg*",
-        "arn:aws:ssm:*:*:parameter/*frigg*/*"
-      ]
-    }
-  ]
-}
-```
-
-**What this enables:**
-- Lambda functions can retrieve configuration from SSM Parameter Store
-- Automatic configuration of AWS Parameters and Secrets Lambda Extension layer
-- Secure environment variable management through SSM
-
-## Complete Policy Template
-
-For convenience, here's a single IAM policy that includes all permissions needed for full Frigg functionality:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "FriggCorePermissions",
-      "Effect": "Allow",
-      "Action": [
-        "sts:GetCallerIdentity",
-        "cloudformation:*",
-        "lambda:*", 
-        "apigateway:*",
-        "logs:*",
-        "sqs:*",
-        "sns:*",
-        "cloudwatch:*",
-        "ec2:Describe*",
-        "ec2:CreateVpcEndpoint",
-        "ec2:DeleteVpcEndpoint",
-        "ec2:ModifyVpcEndpoint",
-        "kms:ListKeys",
-        "kms:DescribeKey", 
-        "kms:GenerateDataKey",
-        "kms:Decrypt",
-        "ssm:GetParameter*"
-      ],
-      "Resource": "*"
-    },
-    {
-      "Sid": "S3DeploymentBuckets",
-      "Effect": "Allow",
-      "Action": [
-        "s3:*"
-      ],
-      "Resource": [
-        "arn:aws:s3:::*serverless*",
-        "arn:aws:s3:::*serverless*/*"
-      ]
-    },
-    {
-      "Sid": "IAMRoleManagement",
-      "Effect": "Allow",
-      "Action": [
-        "iam:CreateRole",
-        "iam:DeleteRole",
-        "iam:GetRole", 
-        "iam:PassRole",
-        "iam:PutRolePolicy",
-        "iam:DeleteRolePolicy",
-        "iam:GetRolePolicy",
-        "iam:AttachRolePolicy",
-        "iam:DetachRolePolicy",
-        "iam:TagRole",
-        "iam:UntagRole",
-        "iam:ListPolicyVersions"
-      ],
-      "Resource": "arn:aws:iam::*:role/*"
-    }
-  ]
-}
-```
-
-## Security Improvements (Updated)
-
-### Scoped Resource Permissions
-
-This policy has been updated to follow the principle of least privilege by scoping permissions to Frigg-specific resources:
-
-**Before (Overly Broad):**
-```json
-"Resource": "*"  // ❌ Too permissive
-```
-
-**After (Frigg-Specific):**
-```json
-"Resource": [
-  "arn:aws:lambda:*:*:function:*frigg*"      // ✅ Only functions containing "frigg"
-]
-```
-
-### Key Security Enhancements
-
-1. **CloudFormation Stacks**: Limited to stacks containing "frigg" in the name
-2. **Lambda Functions**: Scoped to functions containing "frigg" in the name
-3. **IAM Roles**: Restricted to roles containing "frigg" (including Lambda execution roles)
-4. **SQS/SNS**: Limited to queues and topics containing "frigg" in the name
-5. **Logs & Monitoring**: Scoped to Lambda log groups for Frigg functions and CloudWatch alarms containing "frigg"
-6. **KMS**: Added ViaService condition to restrict usage to Lambda and S3 services only
-7. **SSM Parameters**: Limited to parameter paths containing "frigg" in the path structure
-
-### Naming Convention Requirements
-
-For these permissions to work properly, ensure your Frigg applications follow the naming convention of including "frigg" in resource names:
-
-✅ **Good Examples:**
-- `my-frigg-app-dev` (CloudFormation stack)
-- `integration-frigg-service-auth` (Lambda function)
-- `customer-frigg-platform-prod-auth` (Lambda function)
-- `/my-frigg-app/prod/database-url` (SSM parameter)
-- `internal-error-queue-dev` (SQS queue - special pattern for error queues)
-
-❌ **Won't Match:**
-- `my-integration-app-dev` (no "frigg" in name)
-- `customer-platform-prod` (no "frigg" in name)
-
-**Note:** The `internal-error-queue-*` pattern is specifically allowed for error handling queues.
-
-## Security Best Practices
-
-### Principle of Least Privilege
-
-For production deployments, consider creating separate policies for different environments:
-
-1. **Development Policy** - Includes all permissions for full feature testing
-2. **Production Policy** - Only includes permissions for features actually used in production
-3. **CI/CD Policy** - Includes discovery and deployment permissions but restricts sensitive operations
-
-### Resource-Specific Restrictions
-
-You can further restrict permissions by:
-
-```json
-{
-  "Resource": [
-    "arn:aws:cloudformation:us-east-1:YOUR-ACCOUNT-ID:stack/your-app-*/*",
-    "arn:aws:lambda:us-east-1:YOUR-ACCOUNT-ID:function:your-app-*"
-  ]
-}
-```
-
-### Environment Variables for Discovery
-
-The discovery process sets these environment variables during build:
-
-- `AWS_DISCOVERY_VPC_ID` - Your default VPC ID
-- `AWS_DISCOVERY_SECURITY_GROUP_ID` - Default security group ID
-- `AWS_DISCOVERY_SUBNET_ID_1` - First private subnet ID (for Lambda functions)
-- `AWS_DISCOVERY_SUBNET_ID_2` - Second private subnet ID (for Lambda functions, or same as first if only one exists)
-- `AWS_DISCOVERY_PUBLIC_SUBNET_ID` - Public subnet ID (for NAT Gateway placement)
-- `AWS_DISCOVERY_ROUTE_TABLE_ID` - Private route table ID for VPC endpoints
-- `AWS_DISCOVERY_KMS_KEY_ID` - Default KMS key ARN
-
-## Troubleshooting
-
-### Common Permission Issues
-
-1. **Discovery Fails** - Check that you have the discovery-time permissions
-2. **VPC Endpoint Creation Fails** - Ensure you have `ec2:CreateVpcEndpoint` permission
-3. **KMS Operations Fail** - Verify KMS key permissions and that the key exists
-4. **SSM Parameter Access Fails** - Check SSM parameter path permissions
-5. **IAM ListPolicyVersions Error** - If you see "User is not authorized to perform: iam:ListPolicyVersions", ensure your deployment user has this permission (added in recent versions)
-6. **SQS SetQueueAttributes Error** - If you see errors for queues like "internal-error-queue-dev", ensure your IAM policy includes the pattern `arn:aws:sqs:*:*:internal-error-queue-*`
-7. **CloudFormation ListStackResources Error** - If you see "User is not authorized to perform: cloudformation:ListStackResources", update your IAM stack with the latest template that includes this permission
-
-### Fallback Behavior
-
-If AWS discovery fails during build, the framework will:
-- Log a warning message
-- Set fallback environment variables
-- Continue with deployment using safe default values
-- Not fail the build process
-
-### Regional Considerations
-
-Ensure your IAM policy includes permissions for the AWS region where you're deploying:
-- Discovery permissions work across all regions (use `*` in resource ARNs)
-- Deployment permissions should match your target region
-- Some services like IAM are global, others are region-specific
-
-## Using with CI/CD
-
-For automated deployments, ensure your CI/CD system has:
-
-1. **AWS Credentials** configured (access key or IAM role)
-2. **Region** set via `AWS_REGION` environment variable
-3. **This IAM policy** attached to the deployment user/role
-4. **Proper build order** - discovery runs before packaging
-
-Example GitHub Actions configuration:
-
-```yaml
-- name: Configure AWS credentials
-  uses: aws-actions/configure-aws-credentials@v1
-  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: Deploy Frigg App
-  run: |
-    frigg deploy
-```
-
-This policy ensures your Frigg application can successfully discover AWS resources during build time and deploy all necessary infrastructure components during deployment.