@techbulls/encrypted-s3-store 1.0.3 → 1.0.5

package/README.md

@@ -5,6 +5,7 @@ A TypeScript library that provides transparent end-to-end encryption for AWS S3
 ## Features
 
 - **AES-256-GCM Encryption** - Military-grade encryption for all stored objects
+- **Custom Encryption Support** - Bring your own encryption/decryption functions
 - **Configurable Modes** - Choose between `encrypt` (with encryption) or `passthrough` (without encryption)
 - **Scrypt Key Derivation** - Secure memory-hard key derivation using Node.js built-in crypto
 - **Transparent Encryption/Decryption** - Automatic handling during upload and download
@@ -64,11 +65,12 @@ const result = await store.download({
 
 The `S3ObjectStore` constructor accepts the following parameters:
 
-| Parameter | Type       | Required | Description                                                    |
-| --------- | ---------- | -------- | -------------------------------------------------------------- |
-| `client`  | `S3Client` | Yes      | An initialized AWS S3Client instance                           |
-| `key`     | `string`   | Yes\*    | Encryption key for AES-256-GCM                                 |
-| `mode`    | `ModeType` | No       | Operation mode (`'encrypt'` or `'passthrough'`). Default: `'encrypt'` |
+| Parameter          | Type               | Required | Description                                                           |
+| ------------------ | ------------------ | -------- | --------------------------------------------------------------------- |
+| `client`           | `S3Client`         | Yes      | An initialized AWS S3Client instance                                  |
+| `key`              | `string`           | Yes\*    | Encryption key for AES-256-GCM or custom encryption                   |
+| `mode`             | `ModeType`         | No       | Operation mode (`'encrypt'` or `'passthrough'`). Default: `'encrypt'` |
+| `customEncryption` | `CustomEncryption` | No       | Custom encrypt/decrypt functions to replace default AES-256-GCM       |
 
 \*Required when using `encrypt` mode. Can also be provided via `ENCRYPTION_KEY` environment variable.
 
@@ -250,6 +252,77 @@ const result = await store.download({
 });
 ```
 
+### Custom Encryption
+
+You can provide your own encryption/decryption functions to replace the default AES-256-GCM implementation:
+
+```typescript
+import { S3ObjectStore, CustomEncryption } from '@techbulls/encrypted-s3-store';
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+
+const customEncryption: CustomEncryption = {
+  encrypt: (data: Buffer, key: string) => {
+    // Your custom encryption logic
+    const iv = randomBytes(16);
+    const cipher = createCipheriv('aes-256-cbc', Buffer.from(key.padEnd(32)), iv);
+    const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+
+    return {
+      data: encrypted,
+      metadata: {
+        iv: iv.toString('base64'),
+        algorithm: 'aes-256-cbc',
+      },
+    };
+  },
+  decrypt: (data: Buffer, key: string, metadata) => {
+    // Your custom decryption logic using the metadata
+    const iv = Buffer.from(metadata.iv, 'base64');
+    const decipher = createDecipheriv('aes-256-cbc', Buffer.from(key.padEnd(32)), iv);
+    return Buffer.concat([decipher.update(data), decipher.final()]);
+  },
+};
+
+const store = new S3ObjectStore(s3Client, 'my-secret-key', 'encrypt', customEncryption);
+
+// Upload using custom encryption
+await store.upload({
+  Bucket: 'my-bucket',
+  Key: 'file.txt',
+  Body: 'Sensitive data',
+});
+
+// Download using custom decryption
+const result = await store.download({
+  Bucket: 'my-bucket',
+  Key: 'file.txt',
+});
+```
+
+**Custom Encryption Interface:**
+
+```typescript
+interface CustomEncryption {
+  encrypt: (data: Buffer, key: string) => EncryptResult | Promise<EncryptResult>;
+  decrypt: (data: Buffer, key: string, metadata: EncryptionMetadata) => Buffer | Promise<Buffer>;
+}
+
+interface EncryptResult {
+  data: Buffer;           // The encrypted data
+  metadata: EncryptionMetadata;  // Metadata to store for decryption
+}
+
+interface EncryptionMetadata {
+  [key: string]: string;  // Key-value pairs stored in S3 object metadata
+}
+```
+
+**Notes:**
+- Both `encrypt` and `decrypt` functions must be provided together
+- Metadata keys are automatically prefixed with `x-amz-custom-` when stored in S3
+- Custom encryption uses `x-amz-encryption: 'custom'` as the marker in S3 metadata
+- Functions can be synchronous or asynchronous (return Promise)
+
 ### Environment-based Configuration
 
 ```typescript
@@ -282,10 +355,15 @@ Uses scrypt with the following parameters:
 
 Encryption metadata is stored in S3 object metadata:
 
+**Default AES-256-GCM:**
 - `x-amz-iv` - Base64-encoded initialization vector
 - `x-amz-salt` - Base64-encoded salt for key derivation
 - `x-amz-auth-tag` - Base64-encoded authentication tag
-- `x-amz-encryption` - Encryption algorithm identifier
+- `x-amz-encryption` - Set to `aes-256-gcm`
+
+**Custom Encryption:**
+- `x-amz-custom-*` - Custom metadata keys (prefixed automatically)
+- `x-amz-encryption` - Set to `custom`
 
 ## Error Handling
 
@@ -308,7 +386,16 @@ The library is written in TypeScript and exports all types:
 
 ```typescript
 import { S3ObjectStore } from '@techbulls/encrypted-s3-store';
-import type { ModeType, IUpload, IDownload } from '@techbulls/encrypted-s3-store';
+import type {
+  ModeType,
+  IUpload,
+  IDownload,
+  CustomEncryption,
+  EncryptFunction,
+  DecryptFunction,
+  EncryptResult,
+  EncryptionMetadata,
+} from '@techbulls/encrypted-s3-store';
 import type { PutObjectCommandInput, GetObjectCommandInput } from '@techbulls/encrypted-s3-store';
 ```
 
@@ -350,4 +437,4 @@ await store.client.send(
 
 ## License
 
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
+Licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.

package/dist/client.d.ts

@@ -6,7 +6,7 @@
  * @license Apache-2.0
  */
 import { S3Client } from '@aws-sdk/client-s3';
-import { IDownload, IUpload, ModeType } from './types.js';
+import { CustomEncryption, IDownload, IUpload, ModeType } from './types.js';
 import { Readable } from 'node:stream';
 /**
  * S3 client wrapper with transparent end-to-end encryption support.
@@ -40,12 +40,15 @@ export declare class S3ObjectStore {
     algorithm: string;
     /** @type {S3Client} The underlying AWS S3 client instance */
     client: S3Client;
+    /** @type {CustomEncryption | undefined} Optional custom encryption/decryption functions */
+    customEncryption?: CustomEncryption;
     /**
      * Creates a new S3ObjectStore instance.
      *
      * @param client - An initialized AWS S3Client instance
      * @param key - Encryption key for AES-256-GCM. Falls back to ENCRYPTION_KEY environment variable if not provided.
      * @param mode - Operation mode ('encrypt' or 'passthrough'). Defaults to 'encrypt'.
+     * @param customEncryption - Optional custom encryption/decryption functions to replace the default AES-256-GCM implementation.
      * @throws {Error} If no encryption key is provided and ENCRYPTION_KEY environment variable is not set
      *
      * @example
@@ -58,13 +61,24 @@ export declare class S3ObjectStore {
      *
      * // With passthrough mode (no encryption)
      * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     *
+     * // With custom encryption
+     * const store = new S3ObjectStore(s3Client, 'key', 'encrypt', {
+     *   encrypt: (data, key) => ({ data: myEncrypt(data, key), metadata: { myParam: '...' } }),
+     *   decrypt: (data, key, metadata) => myDecrypt(data, key, metadata.myParam)
+     * });
      * ```
      */
-    constructor(client: S3Client, key?: string, mode?: ModeType);
+    constructor(client: S3Client, key?: string, mode?: ModeType, customEncryption?: CustomEncryption);
     /**
      * Uploads data to S3 with optional encryption.
      *
-     * In 'encrypt' mode:
+     * In 'encrypt' mode with custom encryption:
+     * - Calls the custom encrypt function with data and key
+     * - Stores returned metadata with 'x-amz-custom-' prefix in S3 object metadata
+     * - Sets 'x-amz-encryption' to 'custom'
+     *
+     * In 'encrypt' mode (default AES-256-GCM):
      * - Generates a random 12-byte IV (Initialization Vector)
      * - Generates a random 16-byte salt for key derivation
      * - Derives a 256-bit key using scrypt
@@ -109,7 +123,12 @@ export declare class S3ObjectStore {
     /**
      * Downloads data from S3 with optional decryption.
      *
-     * In 'encrypt' mode:
+     * In 'encrypt' mode with custom encryption (x-amz-encryption: 'custom'):
+     * - Extracts custom metadata (removes 'x-amz-custom-' prefix)
+     * - Buffers the encrypted stream
+     * - Calls the custom decrypt function with data, key, and metadata
+     *
+     * In 'encrypt' mode (default AES-256-GCM):
      * - Retrieves encryption metadata (IV, salt, auth tag) from S3 object metadata
      * - Derives the decryption key using scrypt with the stored salt
      * - Decrypts the data using AES-256-GCM

package/dist/client.js

@@ -37,6 +37,7 @@ export class S3ObjectStore {
      * @param client - An initialized AWS S3Client instance
      * @param key - Encryption key for AES-256-GCM. Falls back to ENCRYPTION_KEY environment variable if not provided.
      * @param mode - Operation mode ('encrypt' or 'passthrough'). Defaults to 'encrypt'.
+     * @param customEncryption - Optional custom encryption/decryption functions to replace the default AES-256-GCM implementation.
      * @throws {Error} If no encryption key is provided and ENCRYPTION_KEY environment variable is not set
      *
      * @example
@@ -49,9 +50,15 @@ export class S3ObjectStore {
      *
      * // With passthrough mode (no encryption)
      * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     *
+     * // With custom encryption
+     * const store = new S3ObjectStore(s3Client, 'key', 'encrypt', {
+     *   encrypt: (data, key) => ({ data: myEncrypt(data, key), metadata: { myParam: '...' } }),
+     *   decrypt: (data, key, metadata) => myDecrypt(data, key, metadata.myParam)
+     * });
      * ```
      */
-    constructor(client, key, mode) {
+    constructor(client, key, mode, customEncryption) {
         /** @type {string} Encryption algorithm identifier (always 'aes-256-gcm') */
         this.algorithm = 'aes-256-gcm';
         this.client = client;
@@ -61,11 +68,17 @@ export class S3ObjectStore {
         }
         this.key = (key || envEncryptionKey);
         this.mode = mode ?? 'encrypt';
+        this.customEncryption = customEncryption;
     }
     /**
      * Uploads data to S3 with optional encryption.
      *
-     * In 'encrypt' mode:
+     * In 'encrypt' mode with custom encryption:
+     * - Calls the custom encrypt function with data and key
+     * - Stores returned metadata with 'x-amz-custom-' prefix in S3 object metadata
+     * - Sets 'x-amz-encryption' to 'custom'
+     *
+     * In 'encrypt' mode (default AES-256-GCM):
      * - Generates a random 12-byte IV (Initialization Vector)
      * - Generates a random 16-byte salt for key derivation
      * - Derives a 256-bit key using scrypt
@@ -120,14 +133,6 @@ export class S3ObjectStore {
             }));
         }
         /** Encrypt mode: encrypt data before uploading */
-        /** @type {Buffer} iv - 96-bit IV for GCM mode */
-        const iv = randomBytes(12);
-        /** @type {Buffer} salt - 128-bit salt for scrypt key derivation */
-        const salt = randomBytes(16);
-        /** Derive encryption key using scrypt (memory-hard, resistant to GPU attacks) */
-        const secretKey = await deriveKey(this.key, salt);
-        /** Create AES-256-GCM cipher */
-        const cipher = createCipheriv('aes-256-gcm', secretKey, iv);
         /** Convert input body to Buffer for encryption */
         let data;
         if (typeof input.Body === 'string') {
@@ -142,6 +147,36 @@ export class S3ObjectStore {
         else {
             throw new Error('Unsupported Body type: only string, Buffer, or Uint8Array supported');
         }
+        /** Use custom encryption if provided */
+        if (this.customEncryption) {
+            const result = await this.customEncryption.encrypt(data, this.key);
+            /** Prefix custom metadata keys to avoid conflicts */
+            const customMetadata = {};
+            for (const [key, value] of Object.entries(result.metadata)) {
+                customMetadata[`x-amz-custom-${key}`] = value;
+            }
+            return this.client.send(new PutObjectCommand({
+                ...input,
+                Bucket: input.Bucket || this.bucket,
+                Body: result.data,
+                ContentLength: result.data.length,
+                Metadata: {
+                    ...(input.Metadata || {}),
+                    ...customMetadata,
+                    /** @description Marker indicating custom encryption was used */
+                    'x-amz-encryption': 'custom',
+                },
+            }));
+        }
+        /** Default AES-256-GCM encryption */
+        /** @type {Buffer} iv - 96-bit IV for GCM mode */
+        const iv = randomBytes(12);
+        /** @type {Buffer} salt - 128-bit salt for scrypt key derivation */
+        const salt = randomBytes(16);
+        /** Derive encryption key using scrypt (memory-hard, resistant to GPU attacks) */
+        const secretKey = await deriveKey(this.key, salt);
+        /** Create AES-256-GCM cipher */
+        const cipher = createCipheriv('aes-256-gcm', secretKey, iv);
         /** Encrypt the data */
         const encryptedBody = Buffer.concat([cipher.update(data), cipher.final()]);
         /** Get the GCM authentication tag (ensures data integrity and authenticity) */
@@ -168,7 +203,12 @@ export class S3ObjectStore {
     /**
      * Downloads data from S3 with optional decryption.
      *
-     * In 'encrypt' mode:
+     * In 'encrypt' mode with custom encryption (x-amz-encryption: 'custom'):
+     * - Extracts custom metadata (removes 'x-amz-custom-' prefix)
+     * - Buffers the encrypted stream
+     * - Calls the custom decrypt function with data, key, and metadata
+     *
+     * In 'encrypt' mode (default AES-256-GCM):
      * - Retrieves encryption metadata (IV, salt, auth tag) from S3 object metadata
      * - Derives the decryption key using scrypt with the stored salt
      * - Decrypts the data using AES-256-GCM
@@ -214,10 +254,35 @@ export class S3ObjectStore {
         /** Encrypt mode: decrypt the response */
         /** Extract encryption metadata from S3 object */
         const metadata = response.Metadata || {};
+        const encryption = metadata['x-amz-encryption'];
+        /** Handle custom encryption */
+        if (encryption === 'custom' && this.customEncryption) {
+            /** Extract custom metadata (remove x-amz-custom- prefix) */
+            const customMetadata = {};
+            for (const [key, value] of Object.entries(metadata)) {
+                if (key.startsWith('x-amz-custom-')) {
+                    customMetadata[key.replace('x-amz-custom-', '')] = value;
+                }
+            }
+            /** Buffer the stream to get the encrypted data */
+            const chunks = [];
+            for await (const chunk of response.Body) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            const encryptedData = Buffer.concat(chunks);
+            /** Decrypt using custom decryption function */
+            const decryptedData = await this.customEncryption.decrypt(encryptedData, this.key, customMetadata);
+            return {
+                Body: Readable.from(decryptedData),
+                ContentType: response.ContentType,
+                ContentLength: response.ContentLength,
+                Metadata: response.Metadata,
+            };
+        }
+        /** Default AES-256-GCM decryption */
         const ivBase64 = metadata['x-amz-iv'];
         const saltBase64 = metadata['x-amz-salt'];
         const authTagBase64 = metadata['x-amz-auth-tag'];
-        const encryption = metadata['x-amz-encryption'];
         /** If encryption metadata is missing, return unencrypted stream */
         if (!ivBase64 || !saltBase64 || !authTagBase64 || encryption !== 'aes-256-gcm') {
             return {

package/dist/types.d.ts

@@ -53,3 +53,62 @@ export interface IUpload extends PutObjectCommandInput {
 export interface IDownload extends GetObjectCommandInput {
     Mode?: ModeType;
 }
+/**
+ * Metadata returned by custom encrypt function, stored in S3 object metadata.
+ * All values must be strings as they are stored in S3 metadata headers.
+ */
+export interface EncryptionMetadata {
+    [key: string]: string;
+}
+/**
+ * Result returned by custom encrypt function.
+ *
+ * @property data - The encrypted data as a Buffer
+ * @property metadata - Key-value pairs to be stored in S3 object metadata for decryption
+ */
+export interface EncryptResult {
+    data: Buffer;
+    metadata: EncryptionMetadata;
+}
+/**
+ * Custom encryption function signature.
+ *
+ * @param data - The plaintext data to encrypt
+ * @param key - The encryption key provided to S3ObjectStore
+ * @returns The encrypted data and metadata (can be sync or async)
+ */
+export type EncryptFunction = (data: Buffer, key: string) => Promise<EncryptResult> | EncryptResult;
+/**
+ * Custom decryption function signature.
+ *
+ * @param data - The encrypted data to decrypt
+ * @param key - The encryption key provided to S3ObjectStore
+ * @param metadata - The metadata that was stored during encryption
+ * @returns The decrypted plaintext data (can be sync or async)
+ */
+export type DecryptFunction = (data: Buffer, key: string, metadata: EncryptionMetadata) => Promise<Buffer> | Buffer;
+/**
+ * Custom encryption handler interface.
+ * Both encrypt and decrypt functions must be provided together.
+ *
+ * @example
+ * ```typescript
+ * const customEncryption: CustomEncryption = {
+ *   encrypt: (data, key) => {
+ *     const iv = crypto.randomBytes(16);
+ *     const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
+ *     const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+ *     return { data: encrypted, metadata: { iv: iv.toString('base64') } };
+ *   },
+ *   decrypt: (data, key, metadata) => {
+ *     const iv = Buffer.from(metadata.iv, 'base64');
+ *     const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+ *     return Buffer.concat([decipher.update(data), decipher.final()]);
+ *   }
+ * };
+ * ```
+ */
+export interface CustomEncryption {
+    encrypt: EncryptFunction;
+    decrypt: DecryptFunction;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techbulls/encrypted-s3-store",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",