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:

// 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:

const appDefinition = {
    name: 'my-frigg-app',
    integrations: [
        // your integrations...
    ],
    encryption: {
        fieldLevelEncryptionMethod: 'kms'
    }
}

module.exports = appDefinition;

What Happens Automatically

When fieldLevelEncryptionMethod is set to 'kms', Frigg automatically:

1. Discovers KMS Key: Uses AWS Discovery to find your account's default KMS key

2. Grants KMS Permissions: Adds kms:GenerateDataKey and kms:Decrypt permissions to all Lambda function IAM roles

3. Sets Environment Variable: Configures KMS_KEY_ARN environment variable with discovered key for runtime access

4. Includes KMS Plugin: Adds the serverless-kms-grants plugin to your serverless configuration

5. VPC Integration: Creates KMS VPC Endpoint when VPC is enabled for secure, cost-effective access

Generated Infrastructure

The framework generates the following serverless configuration:

# 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: '${env:AWS_DISCOVERY_KMS_KEY_ID}'  # Discovered via AWS Discovery

Using KMS in Your Code

Accessing the KMS Key ARN

The KMS key ARN is available in your Lambda functions via environment variables:

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:

const { encrypt, decrypt } = require('@friggframework/encrypt');

// Encrypt sensitive data
const encryptedData = await encrypt(sensitiveString);

// Decrypt when needed
const decryptedData = await decrypt(encryptedData);

VPC Integration

KMS with VPC Enabled

When both KMS and VPC are enabled, Frigg automatically optimizes for security and cost:

const appDefinition = {
    encryption: { fieldLevelEncryptionMethod: 'kms' },
    vpc: { enable: true },
    integrations: [/* your integrations */]
};

This configuration automatically:

• Creates KMS VPC Endpoint (~$22/month) for secure, direct KMS access

• Avoids NAT Gateway costs for KMS operations

• Reduces latency by keeping KMS traffic within your VPC

• Improves security by avoiding internet routing for encryption operations

Cost Considerations

Configuration	Monthly Cost	Security	Performance
KMS only (no VPC)	$0	Medium	Good
KMS + VPC (no endpoints)	~$45	High	Good
KMS + VPC + Endpoints	~$67	Very High	Excellent

The VPC endpoint cost is often offset by reduced NAT Gateway data charges for encryption operations.

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

// app-definition.js
const appDefinition = {
    name: 'secure-integration-app',
    integrations: [
        SalesforceIntegration,
        HubspotIntegration
    ],
    encryption: {
        fieldLevelEncryptionMethod: 'kms'
    }
};

module.exports = appDefinition;