@vatsdev/encryption-decryption/README.md

A TypeScript library for secure encryption and decryption using Google Cloud KMS and Secret Manager

# 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:
```json
{
  "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

```typescript
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:

```typescript
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

```typescript
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:
   ```bash
   npm install
   ```
3. Set up environment variables
4. Run tests:
   ```bash
   npm test
   ```

## License

MIT