Field-Level Encryption Service

A TypeScript-based service that provides field-level encryption capabilities using Google Cloud KMS and Secret Manager.

Features

• Field-level encryption for sensitive data
• Integration with Google Cloud KMS for key management
• Secure storage of encrypted data encryption keys (DEKs) in Google Cloud Secret Manager
• Support for multiple encryption algorithms (AES-256-GCM, AES-256-CBC)
• Automatic key rotation and versioning
• Comprehensive error handling and validation
• Support for nested objects and arrays
• Selective field encryption/decryption

Prerequisites

• Node.js (v14 or higher)
• TypeScript
• Google Cloud Platform account with:
  • Cloud KMS enabled
  • Secret Manager enabled
  • Appropriate IAM permissions
• Environment variables:
  • GOOGLE_CLOUD_PROJECT: Your GCP project ID
  • GOOGLE_APPLICATION_CREDENTIALS: Path to your service account key file

Project Structure

src/
├── services/          # Core service implementations
│   ├── encryptionService.ts    # Main encryption service
│   ├── kmsService.ts          # Google Cloud KMS integration
│   └── secretManagerService.ts # Google Cloud Secret Manager integration
├── utils/            # Utility functions and helpers
│   ├── configUtils.ts         # Configuration management
│   ├── encryptionUtils.ts     # Encryption/decryption utilities
│   └── createHash.ts          # Hashing utilities
├── types/            # TypeScript type definitions
│   ├── encryption.ts          # Encryption-related types
│   └── errors.ts              # Error types and codes
├── index.ts          # Main entry point
├── functions.ts      # Function exports
└── types.ts          # Type exports

Core Components

Main Entry Point (index.ts)

• Exports main functionality
• Provides service initialization
• Handles configuration setup

Services Directory

Contains core service implementations for:

• Encryption/Decryption operations
• KMS integration
• Secret Manager integration

Utils Directory

Contains utility functions for:

• Encryption/Decryption helpers
• Data validation
• Error handling
• Configuration management

Types Directory

Contains TypeScript type definitions for:

• Service interfaces
• Configuration types
• Error types

Error Handling

The service implements a comprehensive error handling system with custom error types:

• ConfigurationError: For initialization and configuration issues
• EncryptionError: For encryption/decryption failures
• ValidationError: For input validation failures

Each error type includes specific error codes for better error tracking and handling.

Configuration

Environment Variables

The package uses the following environment variables:

• CONFIG_PATH: Path to your encryption configuration file
• GOOGLE_CLOUD_PROJECT: Your GCP project ID (required)
• GOOGLE_APPLICATION_CREDENTIALS: Path to your service account key file (required)

Configuration File

The encryption configuration file (encryption.json) can be placed in one of these locations:

1. Path specified by CONFIG_PATH environment variable
2. ./config/encryption.json
3. ./src/config/encryption.json
4. ./encryption.json

Example configuration file:

{
  "user": {
    "firstName": {
      "shouldEncrypt": true,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": false,
      "isArrayOfObjects": false
    },
    "lastName": {
      "shouldEncrypt": true,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": false,
      "isArrayOfObjects": false
    },
    "phoneNumber": {
      "shouldEncrypt": true,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": false,
      "isArrayOfObjects": false
    }
  },
  "Company": {
    "vatNumber": {
      "shouldEncrypt": true,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": false,
      "isArrayOfObjects": false
    },
    "crNumber": {
      "shouldEncrypt": true,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": false,
      "isArrayOfObjects": false
    },
    "user": {
      "shouldEncrypt": false,
      "shouldDecrypt": true,
      "shouldHash": false,
      "isObject": true,
      "isArrayOfObjects": false
    }
  }
}

Configuration Options

Each field in the configuration supports the following options:

• shouldEncrypt: Whether the field should be encrypted
• shouldDecrypt: Whether the field should be decrypted
• shouldHash: Whether to create a hash of the field value
• isObject: Whether the field is a nested object
• isArrayOfObjects: Whether the field is an array of objects

Usage Example

import { encryptionService } from '@vatsdev/encryption-decryption-poc';

// Encrypt data
const result = await encryptionService.encryptObject({
    modelName: 'user',
    data: {
        firstName: 'John',
        lastName: 'Doe',
        phoneNumber: '1234567890'
    },
    entityKeyDetailsResult: {
        kmsPath: 'your-kms-path',
        secretId: 'your-secret-id',
        secretNamePath: 'your-secret-name-path',
        encryptedDEK: Buffer.from('your-encrypted-dek')
    }
});

   // Decrypt data
   const decrypted = await encryptionService.decryptObject({
     modelName: 'User',
     data: result.encryptedData,
     entityKeyDetailsResult: result.keyMetadata
   });

Usage Example

Parameters

modelName (string)

The key identifier used in your encryption.json configuration file. This should match the model name you've configured for encryption.

sensitiveData (string)

The data you want to encrypt. This can be any string value that needs to be protected.

entityKeyDetails (object)

An object containing all required fields for encryption and decryption operations:

interface EntityKeyDetails {
    locationId: string | null;    // Google Cloud KMS location ID
    keyRingId: string | null;     // KMS key ring identifier
    keyId: string | null;         // KMS key identifier
    secretId: string | null;      // Secret Manager secret ID
    encryptedDEK?: Buffer | null; // Encrypted Data Encryption Key
    keyVersion: string | null;    // KMS key version
}

Example Usage

import encryptionService from './services/encryptionService';

// Encrypt a field
const encryptedField = await encryptionService.encryptField(
    'model-name',
    'sensitive-data',
    entityKeyDetails
);

// Decrypt a field
const decryptedField = await encryptionService.decryptField(
    'model-name',
    'encrypted-data',
    entityKeyDetails
);

Security Considerations

• All encryption keys are managed by Google Cloud KMS
• DEKs are encrypted before storage
• Automatic key rotation is supported
• Input validation and sanitization
• Comprehensive error handling
• No sensitive data in logs
• Support for nested object encryption
• Selective field encryption/decryption

Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Set up environment variables
4. Run tests:

   npm test

License

MIT