@manishtickets/encryption-decryption NPM

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

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
├── utils/            # Utility functions and helpers
├── types/            # TypeScript type definitions
├── 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

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:

ENCRYPTION_CONFIG_PATH: Path to your encryption configuration file (optional)
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 ENCRYPTION_CONFIG_PATH environment variable 2. ./config/encryption.json 3. ./src/config/encryption.json 4. ./encryption.json

Example configuration file:

{
  "encryptedFields": {
    "User": {
      "Encrypt": [
        {
          "key": "email",
          "shouldHash": true
        },
        {
          "key": "phone",
          "shouldHash": false
        }
      ],
      "Decrypt": [
        {
          "key": "email"
        },
        {
          "key": "phone"
        }
      ]
    }
  }
}

Using in Your Project

Install the package:

npm install @vatsdev/encryption-decryption-poc

Set up environment variables in your project:

# .env file
ENCRYPTION_CONFIG_PATH=/path/to/your/encryption.json
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json

Create your encryption configuration file

Use the package in your code:

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

// Encrypt data
const result = await encryptionService.encryptObject({
  modelName: 'User',
  data: { email: 'user@example.com', phone: '1234567890' },
  clientName: 'your-client'
});

// 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
);