@techbulls/encrypted-s3-store 1.0.6 → 1.1.0

package/README.md

@@ -308,16 +308,17 @@ interface CustomEncryption {
 }
 
 interface EncryptResult {
-  data: Buffer;           // The encrypted data
-  metadata: EncryptionMetadata;  // Metadata to store for decryption
+  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
+  [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
@@ -356,30 +357,17 @@ 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` - Set to `aes-256-gcm`
 
 **Custom Encryption:**
+
 - `x-amz-custom-*` - Custom metadata keys (prefixed automatically)
 - `x-amz-encryption` - Set to `custom`
 
-## Error Handling
-
-The library throws descriptive errors for common issues:
-
-```typescript
-try {
-  await store.upload({ Bucket: 'my-bucket', Key: 'test.txt', Body: 'content' });
-} catch (error) {
-  // Handle errors:
-  // - "Encryption key not provided."
-  // - "Body is required for upload"
-  // - "No body returned from S3"
-}
-```
-
 ## TypeScript
 
 The library is written in TypeScript and exports all types:
@@ -426,6 +414,84 @@ await store.client.send(
 );
 ```
 
+## Advanced Configuration
+
+### Custom Scrypt Parameters
+
+For higher security requirements, you can configure the scrypt key derivation parameters:
+
+```typescript
+const store = new S3ObjectStore(
+  s3Client,
+  'your-key',
+  'encrypt',
+  undefined, // no custom encryption
+  {
+    N: 65536, // 2^16, 4x more secure than default (16384)
+    r: 8, // block size (default)
+    p: 1, // parallelization (default)
+  }
+);
+```
+
+Higher `N` values increase security but also increase computation time and memory usage.
+
+## Error Handling
+
+The library throws descriptive errors. Here's how to handle common cases:
+
+```typescript
+try {
+  await store.upload({
+    Bucket: 'my-bucket',
+    Key: 'file.txt',
+    Body: 'content',
+  });
+} catch (error) {
+  if (error instanceof Error) {
+    if (error.message.includes('Bucket is required')) {
+      console.error('Missing bucket name');
+    } else if (error.message.includes('encryption metadata is missing')) {
+      console.error('Trying to decrypt an unencrypted file - use passthrough mode');
+    } else if (error.message.includes('Failed to upload')) {
+      console.error('S3 upload failed - check credentials and permissions');
+    } else {
+      console.error('Error:', error.message);
+    }
+  }
+}
+```
+
+## Security Best Practices
+
+1. **Key Management**
+   - Never hardcode encryption keys in source code
+   - Use environment variables or secret management services (AWS Secrets Manager, HashiCorp Vault)
+   - Rotate keys periodically
+
+2. **Key Storage**
+   - Store keys in encrypted form when at rest
+   - Never commit keys to version control
+
+3. **Defense in Depth**
+   - Consider using this library WITH S3 server-side encryption for additional protection
+   - Use HTTPS for all S3 operations (default with AWS SDK)
+   - Enable AWS CloudTrail for audit logs
+
+4. **Access Control**
+   - Use least-privilege IAM policies
+   - Enable S3 bucket versioning for recovery
+
+## Platform Support
+
+This library is **Node.js only** and does not support browsers. It uses Node.js built-in modules:
+
+- `node:crypto` (for AES-256-GCM encryption and scrypt)
+- `node:stream` (for streaming)
+- `node:util` (for promisify)
+
+For browser environments, consider using server-side encryption or alternative libraries that use the Web Crypto API.
+
 ## Requirements
 
 - Node.js 18+

package/dist/client.d.ts

@@ -3,11 +3,10 @@
  * Provides transparent encryption/decryption for S3 objects using AES-256-GCM.
  *
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  */
 import { S3Client } from '@aws-sdk/client-s3';
-import { CustomEncryption, IDownload, IUpload, ModeType } from './types.js';
-import { Readable } from 'node:stream';
+import { CustomEncryption, DownloadResult, IDownload, IUpload, ModeType, ScryptOptions } from './types.js';
 /**
  * S3 client wrapper with transparent end-to-end encryption support.
  *
@@ -31,17 +30,17 @@ import { Readable } from 'node:stream';
  */
 export declare class S3ObjectStore {
     /** @type {ModeType} Current operation mode - 'encrypt' or 'passthrough' */
-    mode: ModeType;
+    readonly mode: ModeType;
     /** @type {string} Encryption key used for AES-256-GCM encryption */
-    key: string;
+    private readonly key;
     /** @type {string | undefined} Default S3 bucket for all operations */
-    bucket?: string;
-    /** @type {string} Encryption algorithm identifier (always 'aes-256-gcm') */
-    algorithm: string;
+    readonly bucket?: string;
     /** @type {S3Client} The underlying AWS S3 client instance */
-    client: S3Client;
+    readonly client: S3Client;
     /** @type {CustomEncryption | undefined} Optional custom encryption/decryption functions */
-    customEncryption?: CustomEncryption;
+    private readonly customEncryption?;
+    /** @type {ScryptOptions | undefined} Optional scrypt parameters for key derivation */
+    private readonly scryptOptions?;
     /**
      * Creates a new S3ObjectStore instance.
      *
@@ -49,7 +48,8 @@ export declare class S3ObjectStore {
      * @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
+     * @param scryptOptions - Optional scrypt parameters for key derivation (N, r, p). Defaults: N=16384, r=8, p=1.
+     * @throws {Error} If no encryption key is provided in 'encrypt' mode and ENCRYPTION_KEY environment variable is not set
      *
      * @example
      * ```typescript
@@ -59,17 +59,24 @@ export declare class S3ObjectStore {
      * // With environment variable (ENCRYPTION_KEY)
      * const store = new S3ObjectStore(s3Client);
      *
-     * // With passthrough mode (no encryption)
-     * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     * // With passthrough mode (no encryption key required)
+     * const store = new S3ObjectStore(s3Client, undefined, '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)
      * });
+     *
+     * // With custom scrypt parameters for higher security
+     * const store = new S3ObjectStore(s3Client, 'key', 'encrypt', undefined, {
+     *   N: 65536, // 2^16, 4x more secure than default
+     *   r: 8,
+     *   p: 1,
+     * });
      * ```
      */
-    constructor(client: S3Client, key?: string, mode?: ModeType, customEncryption?: CustomEncryption);
+    constructor(client: S3Client, key?: string, mode?: ModeType, customEncryption?: CustomEncryption, scryptOptions?: ScryptOptions);
     /**
      * Uploads data to S3 with optional encryption.
      *
@@ -154,10 +161,6 @@ export declare class S3ObjectStore {
      * const content = Buffer.concat(chunks).toString('utf8');
      * ```
      */
-    download(input: IDownload): Promise<{
-        Body: Readable;
-        ContentType: string | undefined;
-        ContentLength: number | undefined;
-        Metadata: Record<string, string> | undefined;
-    }>;
+    download(input: IDownload): Promise<DownloadResult>;
 }
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsC,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAElF,OAAO,EACL,gBAAgB,EAChB,cAAc,EAEd,SAAS,EACT,OAAO,EACP,QAAQ,EACR,aAAa,EACd,MAAM,YAAY,CAAC;AA8BpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAE1B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAmB;IAErD,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;gBAED,MAAM,EAAE,QAAQ,EAChB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,QAAQ,EACf,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,aAAa,CAAC,EAAE,aAAa;IAiB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,MAAM,CAAC,KAAK,EAAE,OAAO;IAiK3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC;CAwJ1D"}

package/dist/client.js

@@ -3,12 +3,32 @@
  * Provides transparent encryption/decryption for S3 objects using AES-256-GCM.
  *
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  */
 import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
 import { deriveKey } from './utils.js';
 import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 import { Readable } from 'node:stream';
+/** S3 metadata size limit in bytes */
+const S3_METADATA_SIZE_LIMIT = 2048;
+/**
+ * Calculates the total size of S3 metadata in bytes.
+ * S3 counts both keys and values toward the 2KB limit.
+ */
+function calculateMetadataSize(metadata) {
+    return Object.entries(metadata).reduce((sum, [key, value]) => sum + key.length + value.length, 0);
+}
+/**
+ * Validates that S3 metadata size doesn't exceed the 2KB limit.
+ * @throws {Error} If metadata exceeds the limit
+ */
+function validateMetadataSize(metadata) {
+    const size = calculateMetadataSize(metadata);
+    if (size > S3_METADATA_SIZE_LIMIT) {
+        throw new Error(`S3 metadata size (${size} bytes) exceeds the 2KB limit. ` +
+            'Reduce custom metadata or encryption metadata size.');
+    }
+}
 /**
  * S3 client wrapper with transparent end-to-end encryption support.
  *
@@ -38,7 +58,8 @@ export class S3ObjectStore {
      * @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
+     * @param scryptOptions - Optional scrypt parameters for key derivation (N, r, p). Defaults: N=16384, r=8, p=1.
+     * @throws {Error} If no encryption key is provided in 'encrypt' mode and ENCRYPTION_KEY environment variable is not set
      *
      * @example
      * ```typescript
@@ -48,27 +69,34 @@ export class S3ObjectStore {
      * // With environment variable (ENCRYPTION_KEY)
      * const store = new S3ObjectStore(s3Client);
      *
-     * // With passthrough mode (no encryption)
-     * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     * // With passthrough mode (no encryption key required)
+     * const store = new S3ObjectStore(s3Client, undefined, '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)
      * });
+     *
+     * // With custom scrypt parameters for higher security
+     * const store = new S3ObjectStore(s3Client, 'key', 'encrypt', undefined, {
+     *   N: 65536, // 2^16, 4x more secure than default
+     *   r: 8,
+     *   p: 1,
+     * });
      * ```
      */
-    constructor(client, key, mode, customEncryption) {
-        /** @type {string} Encryption algorithm identifier (always 'aes-256-gcm') */
-        this.algorithm = 'aes-256-gcm';
+    constructor(client, key, mode, customEncryption, scryptOptions) {
         this.client = client;
-        const envEncryptionKey = process.env.ENCRYPTION_KEY;
-        if (!key && !envEncryptionKey) {
-            throw new Error('Encryption key not provided.');
-        }
-        this.key = (key || envEncryptionKey);
         this.mode = mode ?? 'encrypt';
         this.customEncryption = customEncryption;
+        this.scryptOptions = scryptOptions;
+        const envEncryptionKey = process.env.ENCRYPTION_KEY;
+        // Only require encryption key in 'encrypt' mode
+        if (this.mode === 'encrypt' && !key && !envEncryptionKey) {
+            throw new Error('Encryption key is required when mode is "encrypt".');
+        }
+        this.key = (key || envEncryptionKey || '');
     }
     /**
      * Uploads data to S3 with optional encryption.
@@ -120,17 +148,36 @@ export class S3ObjectStore {
      * ```
      */
     async upload(input) {
+        /** Validate required input parameters */
+        const bucket = input.Bucket || this.bucket;
+        if (!bucket) {
+            throw new Error('Bucket is required. Provide it in upload() or set a default bucket.');
+        }
+        if (!input.Key) {
+            throw new Error('Key is required for upload.');
+        }
+        if (input.Key.startsWith('/')) {
+            throw new Error('S3 Key should not start with "/" - use relative paths only.');
+        }
+        if (input.Key.includes('\\')) {
+            throw new Error('S3 Key should not contain backslashes - use forward slashes for paths.');
+        }
         if (!input.Body) {
-            throw new Error('Body is required for upload');
+            throw new Error('Body is required for upload.');
         }
         /** Resolve mode: input.mode takes precedence, fallback to client default */
         const mode = input?.Mode === 'encrypt' || input?.Mode === 'passthrough' ? input.Mode : this.mode;
         /** Passthrough mode: upload without encryption */
         if (mode === 'passthrough') {
-            return this.client.send(new PutObjectCommand({
-                ...input,
-                Bucket: input.Bucket || this.bucket,
-            }));
+            try {
+                return await this.client.send(new PutObjectCommand({
+                    ...input,
+                    Bucket: bucket,
+                }));
+            }
+            catch (error) {
+                throw new Error(`Failed to upload to s3://${bucket}/${input.Key}: ${error instanceof Error ? error.message : error}`);
+            }
         }
         /** Encrypt mode: encrypt data before uploading */
         /** Convert input body to Buffer for encryption */
@@ -149,24 +196,53 @@ export class S3ObjectStore {
         }
         /** Use custom encryption if provided */
         if (this.customEncryption) {
-            const result = await this.customEncryption.encrypt(data, this.key);
+            /** Call custom encryption function with validation */
+            let result;
+            try {
+                result = await this.customEncryption.encrypt(data, this.key);
+            }
+            catch (error) {
+                throw new Error(`Custom encryption function failed: ${error instanceof Error ? error.message : error}`);
+            }
+            /** Validate custom encryption result */
+            if (!result || typeof result !== 'object') {
+                throw new Error('Custom encryption function must return an object with data and metadata.');
+            }
+            if (!Buffer.isBuffer(result.data)) {
+                throw new Error('Custom encryption function must return a Buffer in result.data.');
+            }
+            if (!result.metadata || typeof result.metadata !== 'object') {
+                throw new Error('Custom encryption function must return a metadata object.');
+            }
             /** Prefix custom metadata keys to avoid conflicts */
             const customMetadata = {};
             for (const [key, value] of Object.entries(result.metadata)) {
+                /** Validate custom metadata keys don't use reserved prefix */
+                if (key.startsWith('x-amz-')) {
+                    throw new Error(`Custom encryption metadata key "${key}" cannot start with "x-amz-" as it is reserved. ` +
+                        'Please use a different key name.');
+                }
                 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',
-                },
-            }));
+            /** Construct final metadata and validate size */
+            const finalMetadata = {
+                ...(input.Metadata || {}),
+                ...customMetadata,
+                'x-amz-encryption': 'custom',
+            };
+            validateMetadataSize(finalMetadata);
+            try {
+                return await this.client.send(new PutObjectCommand({
+                    ...input,
+                    Bucket: bucket,
+                    Body: result.data,
+                    ContentLength: result.data.length,
+                    Metadata: finalMetadata,
+                }));
+            }
+            catch (error) {
+                throw new Error(`Failed to upload to s3://${bucket}/${input.Key}: ${error instanceof Error ? error.message : error}`);
+            }
         }
         /** Default AES-256-GCM encryption */
         /** @type {Buffer} iv - 96-bit IV for GCM mode */
@@ -174,31 +250,35 @@ export class S3ObjectStore {
         /** @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);
+        const secretKey = await deriveKey(this.key, salt, this.scryptOptions);
         /** 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) */
         const authTag = cipher.getAuthTag();
+        /** Construct final metadata and validate size */
+        const finalMetadata = {
+            ...(input.Metadata || {}),
+            'x-amz-iv': iv.toString('base64'),
+            'x-amz-salt': salt.toString('base64'),
+            'x-amz-auth-tag': authTag.toString('base64'),
+            'x-amz-encryption': 'aes-256-gcm',
+        };
+        validateMetadataSize(finalMetadata);
         /** Upload encrypted data with encryption metadata stored in S3 object metadata */
-        return this.client.send(new PutObjectCommand({
-            ...input,
-            Bucket: input.Bucket || this.bucket,
-            Body: encryptedBody,
-            ContentLength: encryptedBody.length,
-            Metadata: {
-                ...(input.Metadata || {}),
-                /** @description Base64-encoded IV */
-                'x-amz-iv': iv.toString('base64'),
-                /** @description Base64-encoded salt */
-                'x-amz-salt': salt.toString('base64'),
-                /** @description Base64-encoded GCM auth tag */
-                'x-amz-auth-tag': authTag.toString('base64'),
-                /** @description Encryption algorithm identifier */
-                'x-amz-encryption': 'aes-256-gcm',
-            },
-        }));
+        try {
+            return await this.client.send(new PutObjectCommand({
+                ...input,
+                Bucket: bucket,
+                Body: encryptedBody,
+                ContentLength: encryptedBody.length,
+                Metadata: finalMetadata,
+            }));
+        }
+        catch (error) {
+            throw new Error(`Failed to upload to s3://${bucket}/${input.Key}: ${error instanceof Error ? error.message : error}`);
+        }
     }
     /**
      * Downloads data from S3 with optional decryption.
@@ -235,10 +315,24 @@ export class S3ObjectStore {
      * ```
      */
     async download(input) {
+        /** Validate required input parameters */
+        const bucket = input.Bucket || this.bucket;
+        if (!bucket) {
+            throw new Error('Bucket is required. Provide it in download() or set a default bucket.');
+        }
+        if (!input.Key) {
+            throw new Error('Key is required for download.');
+        }
         /** Fetch the object from S3 */
-        const response = await this.client.send(new GetObjectCommand({ ...input, Bucket: input.Bucket || this.bucket }));
+        let response;
+        try {
+            response = await this.client.send(new GetObjectCommand({ ...input, Bucket: bucket }));
+        }
+        catch (error) {
+            throw new Error(`Failed to download from s3://${bucket}/${input.Key}: ${error instanceof Error ? error.message : error}`);
+        }
         if (!response.Body) {
-            throw new Error('No body returned from S3');
+            throw new Error(`No body returned from S3 for s3://${bucket}/${input.Key}`);
         }
         /** Resolve mode: input.mode takes precedence, fallback to client default */
         const mode = input?.Mode === 'encrypt' || input?.Mode === 'passthrough' ? input.Mode : this.mode;
@@ -270,8 +364,17 @@ export class S3ObjectStore {
                 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);
+            /** Decrypt using custom decryption function with validation */
+            let decryptedData;
+            try {
+                decryptedData = await this.customEncryption.decrypt(encryptedData, this.key, customMetadata);
+            }
+            catch (error) {
+                throw new Error(`Custom decryption function failed for s3://${bucket}/${input.Key}: ${error instanceof Error ? error.message : error}`);
+            }
+            if (!Buffer.isBuffer(decryptedData)) {
+                throw new Error('Custom decryption function must return a Buffer.');
+            }
             return {
                 Body: Readable.from(decryptedData),
                 ContentType: response.ContentType,
@@ -283,26 +386,43 @@ export class S3ObjectStore {
         const ivBase64 = metadata['x-amz-iv'];
         const saltBase64 = metadata['x-amz-salt'];
         const authTagBase64 = metadata['x-amz-auth-tag'];
-        /** If encryption metadata is missing, return unencrypted stream */
+        /** If encryption metadata is missing, throw error in encrypt mode */
         if (!ivBase64 || !saltBase64 || !authTagBase64 || encryption !== 'aes-256-gcm') {
-            return {
-                Body: Readable.from(response.Body),
-                ContentType: response.ContentType,
-                ContentLength: response.ContentLength,
-                Metadata: response.Metadata,
-            };
+            throw new Error(`Expected encrypted object but encryption metadata is missing for s3://${input.Bucket}/${input.Key}. ` +
+                'This object may not be encrypted or was encrypted with a different method. ' +
+                'Use mode: "passthrough" to download unencrypted objects.');
         }
         /** Decode encryption parameters from Base64 */
         const iv = Buffer.from(ivBase64, 'base64');
         const salt = Buffer.from(saltBase64, 'base64');
         const authTag = Buffer.from(authTagBase64, 'base64');
+        /** Validate encryption parameter lengths */
+        if (iv.length !== 12) {
+            throw new Error(`Invalid IV length: expected 12 bytes for GCM mode, got ${iv.length} bytes. ` +
+                'The encrypted data may be corrupted.');
+        }
+        if (salt.length !== 16) {
+            throw new Error(`Invalid salt length: expected 16 bytes, got ${salt.length} bytes. ` +
+                'The encrypted data may be corrupted.');
+        }
+        if (authTag.length !== 16) {
+            throw new Error(`Invalid authentication tag length: expected 16 bytes, got ${authTag.length} bytes. ` +
+                'The encrypted data may be corrupted.');
+        }
         /** Derive the decryption key using the same salt used during encryption */
-        const secretKey = await deriveKey(this.key, salt);
+        const secretKey = await deriveKey(this.key, salt, this.scryptOptions);
         /** Create AES-256-GCM decipher and set the authentication tag */
         const decipher = createDecipheriv('aes-256-gcm', secretKey, iv);
         decipher.setAuthTag(authTag);
         /** Pipe the encrypted stream through the decipher to get decrypted output */
         const decryptedStream = response.Body.pipe(decipher);
+        /** Add error handler for decryption stream errors */
+        decryptedStream.on('error', (error) => {
+            const errorMessage = `Decryption failed for s3://${bucket}/${input.Key}. ` +
+                'This may indicate data corruption or wrong encryption key. ' +
+                `Error: ${error.message}`;
+            decryptedStream.destroy(new Error(errorMessage));
+        });
         return {
             Body: decryptedStream,
             ContentType: response.ContentType,
@@ -311,3 +431,4 @@ export class S3ObjectStore {
         };
     }
 }
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module encrypted-s3-store
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  *
  * @example
  * ```typescript
@@ -24,3 +24,4 @@
  */
 export * from './client.js';
 export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -6,7 +6,7 @@
  *
  * @module encrypted-s3-store
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  *
  * @example
  * ```typescript
@@ -24,3 +24,4 @@
  */
 export * from './client.js';
 export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -3,22 +3,30 @@
  * Contains configuration interfaces and utility types used throughout the library.
  *
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  */
 import { GetObjectCommandInput, PutObjectCommandInput } from '@aws-sdk/client-s3';
+import { Readable } from 'node:stream';
 /**
  * Operation mode for the S3ObjectStore.
  * - 'encrypt': Enables transparent AES-256-GCM encryption for all uploads/downloads
  * - 'passthrough': Data is stored and retrieved without encryption
  */
 export type ModeType = 'encrypt' | 'passthrough';
+/**
+ * Supported body types for upload operations.
+ */
+export type UploadBody = string | Buffer | Uint8Array;
 /**
  * Upload input options extending S3 PutObjectCommandInput.
  * Allows specifying a per-operation encryption mode override.
  *
- * @extends PutObjectCommandInput
+ * @extends Omit<PutObjectCommandInput, 'Body'>
  *
- * @property mode - Optional override for the operation mode. If not specified, uses the client's default mode.
+ * @property Bucket - S3 bucket name (required if not set as default)
+ * @property Key - S3 object key (required)
+ * @property Body - Content to upload (string, Buffer, or Uint8Array)
+ * @property Mode - Optional override for the operation mode. If not specified, uses the client's default mode.
  *
  * @example
  * ```typescript
@@ -26,11 +34,12 @@ export type ModeType = 'encrypt' | 'passthrough';
  *   Bucket: 'my-bucket',
  *   Key: 'file.txt',
  *   Body: 'content',
- *   mode: 'passthrough' // Override to skip encryption for this upload
+ *   Mode: 'passthrough' // Override to skip encryption for this upload
  * };
  * ```
  */
-export interface IUpload extends PutObjectCommandInput {
+export interface IUpload extends Omit<PutObjectCommandInput, 'Body'> {
+    Body?: UploadBody;
     Mode?: ModeType;
 }
 /**
@@ -39,20 +48,36 @@ export interface IUpload extends PutObjectCommandInput {
  *
  * @extends GetObjectCommandInput
  *
- * @property mode - Optional override for the operation mode. If not specified, uses the client's default mode.
+ * @property Bucket - S3 bucket name (required if not set as default)
+ * @property Key - S3 object key (required)
+ * @property Mode - Optional override for the operation mode. If not specified, uses the client's default mode.
  *
  * @example
  * ```typescript
  * const downloadInput: IDownload = {
  *   Bucket: 'my-bucket',
  *   Key: 'file.txt',
- *   mode: 'passthrough' // Override to skip decryption for this download
+ *   Mode: 'passthrough' // Override to skip decryption for this download
  * };
  * ```
  */
 export interface IDownload extends GetObjectCommandInput {
     Mode?: ModeType;
 }
+/**
+ * Result returned from download operations.
+ *
+ * @property Body - Readable stream containing decrypted content
+ * @property ContentType - MIME type of the content (if available)
+ * @property ContentLength - Size of the content in bytes (if available)
+ * @property Metadata - S3 object metadata (key-value pairs)
+ */
+export interface DownloadResult {
+    Body: Readable;
+    ContentType?: string;
+    ContentLength?: number;
+    Metadata?: Record<string, string>;
+}
 /**
  * Metadata returned by custom encrypt function, stored in S3 object metadata.
  * All values must be strings as they are stored in S3 metadata headers.
@@ -112,3 +137,28 @@ export interface CustomEncryption {
     encrypt: EncryptFunction;
     decrypt: DecryptFunction;
 }
+/**
+ * Scrypt key derivation parameters.
+ * Higher values increase security but also increase computation time and memory usage.
+ *
+ * @property N - CPU/memory cost parameter. Must be a power of 2. Default: 16384 (2^14).
+ *               Higher values increase resistance to brute-force attacks.
+ * @property r - Block size parameter. Default: 8.
+ * @property p - Parallelization parameter. Default: 1.
+ *
+ * @example
+ * ```typescript
+ * // For higher security (slower)
+ * const store = new S3ObjectStore(s3Client, 'key', 'encrypt', undefined, {
+ *   N: 65536, // 2^16, 4x more secure than default
+ *   r: 8,
+ *   p: 1,
+ * });
+ * ```
+ */
+export interface ScryptOptions {
+    N?: number;
+    r?: number;
+    p?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,OAAQ,SAAQ,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC;IAClE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,SAAU,SAAQ,qBAAqB;IACtD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;AAEpG;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,kBAAkB,KACzB,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ"}

package/dist/types.js

@@ -3,6 +3,7 @@
  * Contains configuration interfaces and utility types used throughout the library.
  *
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  */
 export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils.d.ts

@@ -1,10 +1,11 @@
+import { ScryptOptions } from './types.js';
 /**
  * Derives a 256-bit encryption key from a password using scrypt.
  *
  * Scrypt is a memory-hard key derivation function that provides strong
  * resistance against brute-force attacks, including GPU-based attacks.
  *
- * Security parameters:
+ * Default security parameters:
  * - N (cost): 16384 (2^14) - CPU/memory cost parameter
  * - r (blockSize): 8 - block size parameter
  * - p (parallelization): 1 - parallelization parameter
@@ -12,6 +13,7 @@
  *
  * @param key - The user's encryption password/key
  * @param salt - Random salt (should be 16 bytes, stored with encrypted data)
+ * @param options - Optional scrypt parameters to override defaults
  * @returns Promise resolving to 32-byte Buffer containing the derived key
  * @throws {Error} If encryption key is empty or not provided
  *
@@ -20,8 +22,12 @@
  * const salt = crypto.randomBytes(16);
  * const derivedKey = await deriveKey('my-secret-password', salt);
  * // derivedKey is a 32-byte Buffer suitable for AES-256
+ *
+ * // With custom parameters for higher security
+ * const derivedKey = await deriveKey('password', salt, { N: 65536 });
  * ```
  *
  * @see https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback
  */
-export declare const deriveKey: (key: string, salt: Buffer) => Promise<Buffer>;
+export declare const deriveKey: (key: string, salt: Buffer, options?: ScryptOptions) => Promise<Buffer>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAU3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,MAAM,MAAM,EACZ,UAAU,aAAa,KACtB,OAAO,CAAC,MAAM,CAkBhB,CAAC"}

package/dist/utils.js

@@ -2,19 +2,23 @@
  * @fileoverview Utility functions for encryption key derivation.
  *
  * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
+ * @license MIT
  */
 import { scrypt } from 'node:crypto';
 import { promisify } from 'node:util';
 /** Promisified version of Node.js scrypt function */
 const scryptAsync = promisify(scrypt);
+/** Default scrypt parameters */
+const DEFAULT_SCRYPT_N = 16384; // 2^14
+const DEFAULT_SCRYPT_R = 8;
+const DEFAULT_SCRYPT_P = 1;
 /**
  * Derives a 256-bit encryption key from a password using scrypt.
  *
  * Scrypt is a memory-hard key derivation function that provides strong
  * resistance against brute-force attacks, including GPU-based attacks.
  *
- * Security parameters:
+ * Default security parameters:
  * - N (cost): 16384 (2^14) - CPU/memory cost parameter
  * - r (blockSize): 8 - block size parameter
  * - p (parallelization): 1 - parallelization parameter
@@ -22,6 +26,7 @@ const scryptAsync = promisify(scrypt);
  *
  * @param key - The user's encryption password/key
  * @param salt - Random salt (should be 16 bytes, stored with encrypted data)
+ * @param options - Optional scrypt parameters to override defaults
  * @returns Promise resolving to 32-byte Buffer containing the derived key
  * @throws {Error} If encryption key is empty or not provided
  *
@@ -30,24 +35,27 @@ const scryptAsync = promisify(scrypt);
  * const salt = crypto.randomBytes(16);
  * const derivedKey = await deriveKey('my-secret-password', salt);
  * // derivedKey is a 32-byte Buffer suitable for AES-256
+ *
+ * // With custom parameters for higher security
+ * const derivedKey = await deriveKey('password', salt, { N: 65536 });
  * ```
  *
  * @see https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback
  */
-export const deriveKey = async (key, salt) => {
+export const deriveKey = async (key, salt, options) => {
     if (!key) {
         throw new Error('Encryption key is required');
     }
+    const N = options?.N ?? DEFAULT_SCRYPT_N;
+    const r = options?.r ?? DEFAULT_SCRYPT_R;
+    const p = options?.p ?? DEFAULT_SCRYPT_P;
     /**
      * Derive key using scrypt with secure parameters.
-     * - N=16384: Memory cost (must be power of 2)
-     * - r=8: Block size
-     * - p=1: Parallelization factor
+     * - N: Memory cost (must be power of 2)
+     * - r: Block size
+     * - p: Parallelization factor
      */
-    const derivedKey = await scryptAsync(key, salt, 32, {
-        N: 16384,
-        r: 8,
-        p: 1,
-    });
+    const derivedKey = await scryptAsync(key, salt, 32, { N, r, p });
     return derivedKey;
 };
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAsC,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,qDAAqD;AACrD,MAAM,WAAW,GAAG,SAAS,CAA6D,MAAM,CAAC,CAAC;AAElG,gCAAgC;AAChC,MAAM,gBAAgB,GAAG,KAAK,CAAC,CAAC,OAAO;AACvC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,GAAW,EACX,IAAY,EACZ,OAAuB,EACN,EAAE;IACnB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,gBAAgB,CAAC;IACzC,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,gBAAgB,CAAC;IACzC,MAAM,CAAC,GAAG,OAAO,EAAE,CAAC,IAAI,gBAAgB,CAAC;IAEzC;;;;;OAKG;IACH,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAEjE,OAAO,UAAoB,CAAC;AAC9B,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techbulls/encrypted-s3-store",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Encrypt and decrypt S3 objects with ease",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,12 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "npm run clean && npm run lint && npm run build"
+    "test": "vitest run",
+    "test:unit": "vitest run --exclude='**/integration.test.ts'",
+    "test:integration": "vitest run src/__tests__/integration.test.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run clean && npm run lint && npm run test:unit && npm run build"
   },
   "keywords": [
     "s3",
@@ -55,14 +60,19 @@
     "@aws-sdk/client-s3": "^3.958.0",
     "@aws-sdk/types": "^3.957.0",
     "@eslint/js": "^9.39.2",
+    "@smithy/util-stream": "^4.5.10",
     "@types/node": "^25.0.3",
     "@typescript-eslint/eslint-plugin": "^8.50.1",
     "@typescript-eslint/parser": "^8.50.1",
+    "@vitest/coverage-v8": "^4.0.17",
+    "aws-sdk-client-mock": "^4.1.0",
+    "aws-sdk-client-mock-jest": "^4.1.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "prettier": "^3.7.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.50.1"
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^4.0.17"
   }
 }