feature: Frigg 2.0 features

.gitignore

@@ -25,3 +25,6 @@ yarn-error.log*
 .npmrc
 .autorc
 /.nx/
+
+CLAUDE.md
+/.claude

README.md

@@ -5,7 +5,7 @@
 
 <img src="docs/FriggLogo.svg" style="width:250px">
 
-**Frigg** is a **Framework** that powers **direct/native integrations** between your product and external software partners.
+**Frigg** is a **Framework** that powers **direct/native integrations** between your product and external software partners. It's full of opinionated structured code that gets you to integration development faster. Yup, another "don't rebuild the wheel. Build the car." thing. Better yet, build the rocket ship.
 
 Build enterprise-grade integrations as simply as _`create-frigg-app`_.
 

docs/SUMMARY.md

@@ -29,6 +29,8 @@
 * [API Module Definition and Functions](reference/api-module-definition-and-functions.md)
 * [Architecture](reference/architecture.md)
 * [Data Model](reference/data-model.md)
+* [Encryption and Security](reference/encryption-and-security.md)
+* [VPC Configuration](reference/vpc-configuration.md)
 * [API Reference](reference/api-reference.md)
 
 ## 🔌 API Modules

docs/reference/encryption-and-security.md

@@ -0,0 +1,171 @@
+# Encryption and Security
+
+## Overview
+
+Frigg provides built-in support for data encryption to help you secure sensitive information in your integrations. The framework automatically configures AWS KMS (Key Management Service) for field-level encryption when enabled in your application definition.
+
+## Default Encryption: AES Keys
+
+### Out-of-the-Box Encryption
+
+By default, Frigg uses a simple AES key-based encryption system that works without any additional configuration. This system uses environment variables to manage encryption keys:
+
+```javascript
+// Current encryption key
+process.env.AES_KEY_ID       // Key identifier
+process.env.AES_KEY          // Actual encryption key
+
+// For key rotation support
+process.env.DEPRECATED_AES_KEY_ID    // Previous key identifier  
+process.env.DEPRECATED_AES_KEY       // Previous encryption key
+```
+
+
+## Automatic KMS Configuration
+
+### Enable KMS in Your App Definition
+
+To enable automatic KMS configuration, add the `encryption` property to your App Definition:
+
+```javascript
+const appDefinition = {
+    name: 'my-frigg-app',
+    integrations: [
+        // your integrations...
+    ],
+    encryption: {
+        useDefaultKMSForFieldLevelEncryption: true
+    }
+}
+
+module.exports = appDefinition;
+```
+
+### What Happens Automatically
+
+When `useDefaultKMSForFieldLevelEncryption` is set to `true`, Frigg automatically:
+
+1. **Grants KMS Permissions**: Adds `kms:GenerateDataKey` and `kms:Decrypt` permissions to all Lambda function IAM roles
+2. **Sets Environment Variable**: Configures `KMS_KEY_ARN` environment variable for runtime access
+3. **Includes KMS Plugin**: Adds the `serverless-kms-grants` plugin to your serverless configuration
+4. **Configures Default Keys**: Uses AWS default KMS keys (`kmsKeyId: '*'`) for encryption operations
+
+### Generated Infrastructure
+
+The framework generates the following serverless configuration:
+
+```yaml
+# IAM Permissions
+provider:
+  iamRoleStatements:
+    - Effect: Allow
+      Action:
+        - kms:GenerateDataKey
+        - kms:Decrypt
+      Resource: 
+        - '${self:custom.kmsGrants.kmsKeyId}'
+
+# Environment Variables
+provider:
+  environment:
+    KMS_KEY_ARN: '${self:custom.kmsGrants.kmsKeyId}'
+
+# Plugins
+plugins:
+  - serverless-kms-grants
+
+# Custom Configuration
+custom:
+  kmsGrants:
+    kmsKeyId: '*'
+```
+
+## Using KMS in Your Code
+
+### Accessing the KMS Key ARN
+
+The KMS key ARN is available in your Lambda functions via environment variables:
+
+```javascript
+const kmsKeyArn = process.env.KMS_KEY_ARN;
+
+// Use with AWS SDK for encryption operations
+const { KMSClient, GenerateDataKeyCommand, DecryptCommand } = require('@aws-sdk/client-kms');
+
+const kmsClient = new KMSClient({ region: 'us-east-1' });
+```
+
+### Integration with Frigg Encrypt Module
+
+If you're using the `@friggframework/encrypt` module, it will automatically use the configured KMS key:
+
+```javascript
+const { encrypt, decrypt } = require('@friggframework/encrypt');
+
+// Encrypt sensitive data
+const encryptedData = await encrypt(sensitiveString);
+
+// Decrypt when needed
+const decryptedData = await decrypt(encryptedData);
+```
+
+## Security Best Practices
+
+### When to Use KMS
+
+Enable KMS encryption when your integrations handle:
+
+- Personal Identifiable Information (PII)
+- Financial data
+- Authentication tokens (beyond basic OAuth)
+- Sensitive business data
+- Healthcare information (PHI)
+
+### Key Management
+
+- **Default Keys**: Frigg uses AWS default KMS keys (`*`) for simplicity
+- **Custom Keys**: For enhanced security, consider creating dedicated KMS keys per environment
+- **Key Rotation**: AWS automatically rotates default keys annually
+
+## Deployment Considerations
+
+### Prerequisites
+
+Ensure your deployment environment has:
+
+1. **IAM Permissions**: Deployment role needs KMS permissions to create grants
+2. **KMS Access**: Lambda execution role will have KMS permissions after deployment
+
+### Environment Isolation
+
+KMS configurations are environment-specific:
+
+- **Development**: Uses same default keys for testing
+- **Staging**: Can use environment-specific keys
+- **Production**: Should use dedicated production keys for maximum security
+
+### Version Requirements
+
+- **Framework Version**: Requires `@friggframework/devtools` v2.1.0+
+- **AWS Provider**: Compatible with all AWS regions
+- **Node.js**: Works with all supported Node.js versions (16.x, 18.x, 20.x)
+
+## Examples
+
+### Basic Setup
+
+```javascript
+// app-definition.js
+const appDefinition = {
+    name: 'secure-integration-app',
+    integrations: [
+        SalesforceIntegration,
+        HubspotIntegration
+    ],
+    encryption: {
+        useDefaultKMSForFieldLevelEncryption: true
+    }
+};
+
+module.exports = appDefinition;
+```

docs/reference/vpc-configuration.md

@@ -0,0 +1,186 @@
+# VPC Configuration
+
+## Overview
+
+Frigg provides **complete VPC infrastructure automation** for your Lambda functions. When enabled, it creates a production-ready VPC with all necessary components: VPC, subnets, NAT Gateway, Internet Gateway, route tables, security groups, and VPC endpoints.
+
+## Quick Start - Zero Configuration
+
+Enable VPC with a single flag - Frigg handles everything:
+
+```javascript
+const appDefinition = {
+    name: 'my-frigg-app',
+    integrations: [
+        // your integrations...
+    ],
+    vpc: {
+        enable: true  // That's it! Complete VPC infrastructure is created automatically
+    }
+}
+
+module.exports = appDefinition;
+```
+
+## What Gets Created Automatically
+
+When `vpc.enable` is `true`, Frigg creates a complete, production-ready VPC infrastructure:
+
+### Core VPC Infrastructure
+- **VPC** with DNS resolution enabled (`10.0.0.0/16` CIDR)
+- **Internet Gateway** for internet connectivity
+- **Public Subnet** for NAT Gateway (`10.0.1.0/24`)
+- **2 Private Subnets** in different AZs for Lambda functions (`10.0.2.0/24`, `10.0.3.0/24`)
+- **NAT Gateway** with Elastic IP for private subnet internet access
+- **Route Tables** properly configured for internet routing
+
+### Security Groups
+- **Lambda Security Group** with outbound rules for:
+  - HTTPS (443) - API calls
+  - HTTP (80) - HTTP requests  
+  - DNS (53 TCP/UDP) - Domain resolution
+
+### VPC Endpoints (Cost Optimization)
+- **S3 Gateway Endpoint** (free) - Direct S3 access without NAT costs
+- **DynamoDB Gateway Endpoint** (free) - Direct DynamoDB access
+- **KMS Interface Endpoint** (paid, ~$22/month) - Only if KMS encryption enabled
+- **Secrets Manager Interface Endpoint** (paid, ~$22/month) - For secure secret access
+
+### IAM Permissions
+- **ENI Management** permissions for Lambda VPC operations
+
+## Configuration Options
+
+### Basic VPC (Zero Configuration)
+```javascript
+vpc: {
+    enable: true  // Creates complete VPC infrastructure with defaults
+}
+```
+
+### Custom CIDR Block
+```javascript
+vpc: {
+    enable: true,
+    cidrBlock: '10.1.0.0/16'  // Custom VPC CIDR (default: 10.0.0.0/16)
+}
+```
+
+### Disable VPC Endpoints
+```javascript
+vpc: {
+    enable: true,
+    enableVPCEndpoints: false  // Disable VPC endpoints (use NAT for all traffic)
+}
+```
+
+### Use Existing Infrastructure
+```javascript
+vpc: {
+    enable: true,
+    securityGroupIds: ['sg-existing123'],  // Use existing security groups
+    subnetIds: ['subnet-existing456']      // Use existing subnets
+    // Skips infrastructure creation, only enables VPC for Lambda
+}
+```
+
+## Generated Infrastructure
+
+### Complete CloudFormation Resources
+```yaml
+# VPC and Networking
+- AWS::EC2::VPC (10.0.0.0/16)
+- AWS::EC2::InternetGateway
+- AWS::EC2::NatGateway + Elastic IP
+- AWS::EC2::Subnet (1 public, 2 private)
+- AWS::EC2::RouteTable (public + private routing)
+
+# Security
+- AWS::EC2::SecurityGroup (Lambda + VPC Endpoints)
+
+# VPC Endpoints (optional)
+- AWS::EC2::VPCEndpoint (S3, DynamoDB - free)
+- AWS::EC2::VPCEndpoint (KMS, Secrets Manager - paid)
+
+# Lambda Configuration
+provider:
+  vpc:
+    securityGroupIds: [!Ref FriggLambdaSecurityGroup]
+    subnetIds: 
+      - !Ref FriggPrivateSubnet1
+      - !Ref FriggPrivateSubnet2
+```
+
+### Cost Optimization
+```javascript
+// Minimal cost setup
+vpc: {
+    enable: true,
+    enableVPCEndpoints: false  // Use NAT only, skip interface endpoints
+}
+
+// Optimized setup (recommended)
+vpc: {
+    enable: true  // Default: includes free S3/DynamoDB endpoints
+}
+```
+
+### Environment-Specific VPC
+```javascript
+const appDefinition = {
+    vpc: {
+        enable: process.env.STAGE === 'prod',  // Only enable VPC in production
+        cidrBlock: process.env.STAGE === 'prod' ? '10.0.0.0/16' : '10.1.0.0/16'
+    }
+};
+```
+
+## When to Use VPC
+
+### ✅ Enable VPC For:
+- **Production applications** requiring network isolation
+- **Compliance requirements** (SOC 2, HIPAA, PCI DSS)
+- **Integration with existing VPC resources**
+- **Enhanced security posture**
+- **Cost optimization** via VPC endpoints
+
+## Migration and Compatibility
+
+### Existing Applications
+- **Zero breaking changes** - add `vpc: { enable: true }` when ready
+- **Gradual rollout** - enable per environment
+- **Rollback friendly** - disable flag to revert
+
+### Override Existing Infrastructure
+```javascript
+// Use your existing VPC resources instead of auto-created ones
+vpc: {
+    enable: true,
+    securityGroupIds: ['sg-your-existing'],
+    subnetIds: ['subnet-your-existing-1', 'subnet-your-existing-2']
+}
+```
+
+
+### Production-Optimized Setup
+```javascript
+const appDefinition = {
+    encryption: { useDefaultKMSForFieldLevelEncryption: true },
+    vpc: {
+        enable: true,
+        cidrBlock: '10.0.0.0/16',
+        enableVPCEndpoints: true  // Include KMS endpoint for encryption
+    }
+};
+```
+
+### Existing Infrastructure Integration
+```javascript
+const appDefinition = {
+    vpc: {
+        enable: true,
+        securityGroupIds: ['sg-prod-lambda-12345'],
+        subnetIds: ['subnet-prod-private-1', 'subnet-prod-private-2']
+    }
+};
+``` 

lerna.json

@@ -1,7 +1,7 @@
 {
   "$schema": "node_modules/lerna/schemas/lerna-schema.json",
-  "version": "1.2.2",
+  "version": "2.0.0-next.0",
   "packages": [
     "packages/*"
   ]
-}
+}