@techbulls/encrypted-s3-store 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Core S3ObjectStore client implementation.
+ * Provides transparent encryption/decryption for S3 objects using AES-256-GCM.
+ *
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+import { IDownload, IUpload, ModeType } from './types.js';
+import { Readable } from 'node:stream';
+/** Re-export all AWS S3 SDK exports for convenience */
+export * from '@aws-sdk/client-s3';
+/**
+ * S3 client wrapper with transparent end-to-end encryption support.
+ *
+ * Wraps an AWS S3 client to provide automatic encryption on upload
+ * and decryption on download using AES-256-GCM with scrypt key derivation.
+ *
+ * @example
+ * ```typescript
+ * // Create an S3 client
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * // Create an encrypted store wrapper
+ * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+ *
+ * // Upload encrypted data
+ * await store.upload({ Bucket: 'my-bucket', Key: 'secret.txt', Body: 'Sensitive data' });
+ *
+ * // Download and decrypt
+ * const { Body } = await store.download({ Bucket: 'my-bucket', Key: 'secret.txt' });
+ * ```
+ */
+export declare class S3ObjectStore {
+    /** @type {ModeType} Current operation mode - 'encrypt' or 'passthrough' */
+    mode: ModeType;
+    /** @type {string} Encryption key used for AES-256-GCM encryption */
+    key: string;
+    /** @type {string | undefined} Default S3 bucket for all operations */
+    bucket?: string;
+    /** @type {string} Encryption algorithm identifier (always 'aes-256-gcm') */
+    algorithm: string;
+    /** @type {S3Client} The underlying AWS S3 client instance */
+    client: S3Client;
+    /**
+     * 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'.
+     * @throws {Error} If no encryption key is provided and ENCRYPTION_KEY environment variable is not set
+     *
+     * @example
+     * ```typescript
+     * // With explicit key
+     * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+     *
+     * // With environment variable (ENCRYPTION_KEY)
+     * const store = new S3ObjectStore(s3Client);
+     *
+     * // With passthrough mode (no encryption)
+     * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     * ```
+     */
+    constructor(client: S3Client, key?: string, mode?: ModeType);
+    /**
+     * Uploads data to S3 with optional encryption.
+     *
+     * In 'encrypt' mode:
+     * - Generates a random 12-byte IV (Initialization Vector)
+     * - Generates a random 16-byte salt for key derivation
+     * - Derives a 256-bit key using scrypt
+     * - Encrypts the data using AES-256-GCM
+     * - Stores encryption metadata (IV, salt, auth tag) in S3 object metadata
+     *
+     * In 'passthrough' mode:
+     * - Uploads data directly without encryption
+     *
+     * @param input - S3 PutObject parameters with optional mode override
+     * @returns Promise resolving to the S3 PutObject response
+     * @throws {Error} If Body is not provided
+     * @throws {Error} If Body type is not supported (only string, Buffer, Uint8Array)
+     *
+     * @example
+     * ```typescript
+     * // Upload a string
+     * await store.upload({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'Hello World' });
+     *
+     * // Upload a Buffer
+     * await store.upload({ Bucket: 'my-bucket', Key: 'data.bin', Body: Buffer.from([0x01, 0x02]) });
+     *
+     * // Upload with custom metadata
+     * await store.upload({
+     *   Bucket: 'my-bucket',
+     *   Key: 'file.txt',
+     *   Body: 'content',
+     *   ContentType: 'text/plain',
+     *   Metadata: { 'custom-header': 'value' }
+     * });
+     *
+     * // Upload without encryption (per-operation override)
+     * await store.upload({
+     *   Bucket: 'my-bucket',
+     *   Key: 'public.txt',
+     *   Body: 'not sensitive',
+     *   mode: 'passthrough'
+     * });
+     * ```
+     */
+    upload(input: IUpload): Promise<import("@aws-sdk/client-s3").PutObjectCommandOutput>;
+    /**
+     * Downloads data from S3 with optional decryption.
+     *
+     * In 'encrypt' mode:
+     * - 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
+     * - Verifies data integrity using the authentication tag
+     *
+     * In 'passthrough' mode:
+     * - Returns the data stream directly without decryption
+     *
+     * @param input - S3 GetObject parameters with optional mode override
+     * @returns Promise resolving to an object containing the decrypted Body stream and metadata
+     * @throws {Error} If no body is returned from S3
+     * @throws {Error} If authentication tag verification fails (data tampering detected)
+     *
+     * @example
+     * ```typescript
+     * const { Body, ContentType } = await store.download({ Bucket: 'my-bucket', Key: 'file.txt' });
+     *
+     * // Read the stream
+     * const chunks: Buffer[] = [];
+     * for await (const chunk of Body) {
+     *   chunks.push(chunk);
+     * }
+     * const content = Buffer.concat(chunks).toString('utf8');
+     * ```
+     */
+    download(input: IDownload): Promise<{
+        Body: Readable;
+        ContentType: string | undefined;
+        ContentLength: number | undefined;
+        Metadata: Record<string, string> | undefined;
+    }>;
+}
+//# 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,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,uDAAuD;AACvD,cAAc,oBAAoB,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa;IACxB,2EAA2E;IAC3E,IAAI,EAAE,QAAQ,CAAC;IAEf,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IAEZ,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4EAA4E;IAC5E,SAAS,SAAiB;IAE1B,6DAA6D;IAC7D,MAAM,EAAE,QAAQ,CAAC;IAEjB;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ;IAW3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,MAAM,CAAC,KAAK,EAAE,OAAO;IAwE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS;;;;;;CAiEhC"}

package/dist/client.js

@@ -0,0 +1,251 @@
+/**
+ * @fileoverview Core S3ObjectStore client implementation.
+ * Provides transparent encryption/decryption for S3 objects using AES-256-GCM.
+ *
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ */
+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';
+/** Re-export all AWS S3 SDK exports for convenience */
+export * from '@aws-sdk/client-s3';
+/**
+ * S3 client wrapper with transparent end-to-end encryption support.
+ *
+ * Wraps an AWS S3 client to provide automatic encryption on upload
+ * and decryption on download using AES-256-GCM with scrypt key derivation.
+ *
+ * @example
+ * ```typescript
+ * // Create an S3 client
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * // Create an encrypted store wrapper
+ * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+ *
+ * // Upload encrypted data
+ * await store.upload({ Bucket: 'my-bucket', Key: 'secret.txt', Body: 'Sensitive data' });
+ *
+ * // Download and decrypt
+ * const { Body } = await store.download({ Bucket: 'my-bucket', Key: 'secret.txt' });
+ * ```
+ */
+export class S3ObjectStore {
+    /**
+     * 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'.
+     * @throws {Error} If no encryption key is provided and ENCRYPTION_KEY environment variable is not set
+     *
+     * @example
+     * ```typescript
+     * // With explicit key
+     * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+     *
+     * // With environment variable (ENCRYPTION_KEY)
+     * const store = new S3ObjectStore(s3Client);
+     *
+     * // With passthrough mode (no encryption)
+     * const store = new S3ObjectStore(s3Client, 'key', 'passthrough');
+     * ```
+     */
+    constructor(client, key, mode) {
+        /** @type {string} Encryption algorithm identifier (always 'aes-256-gcm') */
+        this.algorithm = 'aes-256-gcm';
+        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';
+    }
+    /**
+     * Uploads data to S3 with optional encryption.
+     *
+     * In 'encrypt' mode:
+     * - Generates a random 12-byte IV (Initialization Vector)
+     * - Generates a random 16-byte salt for key derivation
+     * - Derives a 256-bit key using scrypt
+     * - Encrypts the data using AES-256-GCM
+     * - Stores encryption metadata (IV, salt, auth tag) in S3 object metadata
+     *
+     * In 'passthrough' mode:
+     * - Uploads data directly without encryption
+     *
+     * @param input - S3 PutObject parameters with optional mode override
+     * @returns Promise resolving to the S3 PutObject response
+     * @throws {Error} If Body is not provided
+     * @throws {Error} If Body type is not supported (only string, Buffer, Uint8Array)
+     *
+     * @example
+     * ```typescript
+     * // Upload a string
+     * await store.upload({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'Hello World' });
+     *
+     * // Upload a Buffer
+     * await store.upload({ Bucket: 'my-bucket', Key: 'data.bin', Body: Buffer.from([0x01, 0x02]) });
+     *
+     * // Upload with custom metadata
+     * await store.upload({
+     *   Bucket: 'my-bucket',
+     *   Key: 'file.txt',
+     *   Body: 'content',
+     *   ContentType: 'text/plain',
+     *   Metadata: { 'custom-header': 'value' }
+     * });
+     *
+     * // Upload without encryption (per-operation override)
+     * await store.upload({
+     *   Bucket: 'my-bucket',
+     *   Key: 'public.txt',
+     *   Body: 'not sensitive',
+     *   mode: 'passthrough'
+     * });
+     * ```
+     */
+    async upload(input) {
+        if (!input.Body) {
+            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,
+            }));
+        }
+        /** 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') {
+            data = Buffer.from(input.Body, 'utf8');
+        }
+        else if (Buffer.isBuffer(input.Body)) {
+            data = input.Body;
+        }
+        else if (input.Body instanceof Uint8Array) {
+            data = Buffer.from(input.Body);
+        }
+        else {
+            throw new Error('Unsupported Body type: only string, Buffer, or Uint8Array supported');
+        }
+        /** 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();
+        /** 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',
+            },
+        }));
+    }
+    /**
+     * Downloads data from S3 with optional decryption.
+     *
+     * In 'encrypt' mode:
+     * - 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
+     * - Verifies data integrity using the authentication tag
+     *
+     * In 'passthrough' mode:
+     * - Returns the data stream directly without decryption
+     *
+     * @param input - S3 GetObject parameters with optional mode override
+     * @returns Promise resolving to an object containing the decrypted Body stream and metadata
+     * @throws {Error} If no body is returned from S3
+     * @throws {Error} If authentication tag verification fails (data tampering detected)
+     *
+     * @example
+     * ```typescript
+     * const { Body, ContentType } = await store.download({ Bucket: 'my-bucket', Key: 'file.txt' });
+     *
+     * // Read the stream
+     * const chunks: Buffer[] = [];
+     * for await (const chunk of Body) {
+     *   chunks.push(chunk);
+     * }
+     * const content = Buffer.concat(chunks).toString('utf8');
+     * ```
+     */
+    async download(input) {
+        /** Fetch the object from S3 */
+        const response = await this.client.send(new GetObjectCommand({ ...input, Bucket: input.Bucket || this.bucket }));
+        if (!response.Body) {
+            throw new Error('No body returned from S3');
+        }
+        /** Resolve mode: input.mode takes precedence, fallback to client default */
+        const mode = input?.mode === 'encrypt' || input?.mode === 'passthrough' ? input.mode : this.mode;
+        /** Passthrough mode: download without encryption */
+        if (mode === 'passthrough') {
+            return {
+                Body: Readable.from(response.Body),
+                ContentType: response.ContentType,
+                ContentLength: response.ContentLength,
+                Metadata: response.Metadata,
+            };
+        }
+        /** Encrypt mode: decrypt the response */
+        /** Extract encryption metadata from S3 object */
+        const metadata = response.Metadata || {};
+        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 {
+                Body: Readable.from(response.Body),
+                ContentType: response.ContentType,
+                ContentLength: response.ContentLength,
+                Metadata: response.Metadata,
+            };
+        }
+        /** Decode encryption parameters from Base64 */
+        const iv = Buffer.from(ivBase64, 'base64');
+        const salt = Buffer.from(saltBase64, 'base64');
+        const authTag = Buffer.from(authTagBase64, 'base64');
+        /** Derive the decryption key using the same salt used during encryption */
+        const secretKey = await deriveKey(this.key, salt);
+        /** 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);
+        return {
+            Body: decryptedStream,
+            ContentType: response.ContentType,
+            ContentLength: response.ContentLength,
+            Metadata: response.Metadata,
+        };
+    }
+}
+//# 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

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Main entry point for the Encrypted S3 Store library.
+ *
+ * This library provides transparent end-to-end encryption for AWS S3 objects
+ * using AES-256-GCM encryption with scrypt key derivation.
+ *
+ * @module encrypted-s3-store
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ *
+ * @example
+ * ```typescript
+ * import { S3ObjectStore, S3Client } from '@techbulls/encrypted-s3-store';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+ *
+ * // Upload with automatic encryption
+ * await store.upload({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'Hello World' });
+ *
+ * // Download with automatic decryption
+ * const result = await store.download({ Bucket: 'my-bucket', Key: 'file.txt' });
+ * ```
+ */
+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

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Main entry point for the Encrypted S3 Store library.
+ *
+ * This library provides transparent end-to-end encryption for AWS S3 objects
+ * using AES-256-GCM encryption with scrypt key derivation.
+ *
+ * @module encrypted-s3-store
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ *
+ * @example
+ * ```typescript
+ * import { S3ObjectStore, S3Client } from '@techbulls/encrypted-s3-store';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ * const store = new S3ObjectStore(s3Client, 'my-secret-key');
+ *
+ * // Upload with automatic encryption
+ * await store.upload({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'Hello World' });
+ *
+ * // Download with automatic decryption
+ * const result = await store.download({ Bucket: 'my-bucket', Key: 'file.txt' });
+ * ```
+ */
+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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Type definitions for the Encrypted S3 Store library.
+ * Contains configuration interfaces and utility types used throughout the library.
+ *
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ */
+import { GetObjectCommandInput, PutObjectCommandInput } from '@aws-sdk/client-s3';
+/**
+ * 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';
+/**
+ * Upload input options extending S3 PutObjectCommandInput.
+ * Allows specifying a per-operation encryption mode override.
+ *
+ * @extends PutObjectCommandInput
+ *
+ * @property mode - Optional override for the operation mode. If not specified, uses the client's default mode.
+ *
+ * @example
+ * ```typescript
+ * const uploadInput: IUpload = {
+ *   Bucket: 'my-bucket',
+ *   Key: 'file.txt',
+ *   Body: 'content',
+ *   mode: 'passthrough' // Override to skip encryption for this upload
+ * };
+ * ```
+ */
+export interface IUpload extends PutObjectCommandInput {
+    mode?: ModeType;
+}
+/**
+ * Download input options extending S3 GetObjectCommandInput.
+ * Allows specifying a per-operation encryption mode override.
+ *
+ * @extends GetObjectCommandInput
+ *
+ * @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
+ * };
+ * ```
+ */
+export interface IDownload extends GetObjectCommandInput {
+    mode?: ModeType;
+}
+//# 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;AAElF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,OAAQ,SAAQ,qBAAqB;IACpD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAU,SAAQ,qBAAqB;IACtD,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Type definitions for the Encrypted S3 Store library.
+ * Contains configuration interfaces and utility types used throughout the library.
+ *
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ */
+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

@@ -0,0 +1,28 @@
+/**
+ * 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:
+ * - N (cost): 16384 (2^14) - CPU/memory cost parameter
+ * - r (blockSize): 8 - block size parameter
+ * - p (parallelization): 1 - parallelization parameter
+ * - Output: 32 bytes (256 bits for AES-256)
+ *
+ * @param key - The user's encryption password/key
+ * @param salt - Random salt (should be 16 bytes, stored with encrypted data)
+ * @returns Promise resolving to 32-byte Buffer containing the derived key
+ * @throws {Error} If encryption key is empty or not provided
+ *
+ * @example
+ * ```typescript
+ * const salt = crypto.randomBytes(16);
+ * const derivedKey = await deriveKey('my-secret-password', salt);
+ * // derivedKey is a 32-byte Buffer suitable for AES-256
+ * ```
+ *
+ * @see https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback
+ */
+export declare const deriveKey: (key: string, salt: Buffer) => 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":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,SAAS,GAAU,KAAK,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,MAAM,CAkBzE,CAAC"}

package/dist/utils.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Utility functions for encryption key derivation.
+ *
+ * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
+ * @license Apache-2.0
+ */
+import { scrypt } from 'node:crypto';
+import { promisify } from 'node:util';
+/** Promisified version of Node.js scrypt function */
+const scryptAsync = promisify(scrypt);
+/**
+ * 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:
+ * - N (cost): 16384 (2^14) - CPU/memory cost parameter
+ * - r (blockSize): 8 - block size parameter
+ * - p (parallelization): 1 - parallelization parameter
+ * - Output: 32 bytes (256 bits for AES-256)
+ *
+ * @param key - The user's encryption password/key
+ * @param salt - Random salt (should be 16 bytes, stored with encrypted data)
+ * @returns Promise resolving to 32-byte Buffer containing the derived key
+ * @throws {Error} If encryption key is empty or not provided
+ *
+ * @example
+ * ```typescript
+ * const salt = crypto.randomBytes(16);
+ * const derivedKey = await deriveKey('my-secret-password', salt);
+ * // derivedKey is a 32-byte Buffer suitable for AES-256
+ * ```
+ *
+ * @see https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback
+ */
+export const deriveKey = async (key, salt) => {
+    if (!key) {
+        throw new Error('Encryption key is required');
+    }
+    /**
+     * Derive key using scrypt with secure parameters.
+     * - N=16384: Memory cost (must be power of 2)
+     * - r=8: Block size
+     * - p=1: Parallelization factor
+     */
+    const derivedKey = await scryptAsync(key, salt, 32, {
+        N: 16384,
+        r: 8,
+        p: 1,
+    });
+    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,EAAiB,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,qDAAqD;AACrD,MAAM,WAAW,GAAG,SAAS,CAAyD,MAAM,CAAC,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAAE,GAAW,EAAE,IAAY,EAAmB,EAAE;IAC5E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACH,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE;QAClD,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,CAAC;KACL,CAAC,CAAC;IAEH,OAAO,UAAoB,CAAC;AAC9B,CAAC,CAAC"}

package/eslint.config.js

@@ -0,0 +1,23 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import eslintPluginPrettier from 'eslint-plugin-prettier/recommended';
+
+/** @type {import('typescript-eslint').Config} */
+export default [
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintConfigPrettier,
+  eslintPluginPrettier,
+  {
+    ignores: ['dist/**', 'node_modules/**'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: {
+        project: './tsconfig.json',
+      },
+    },
+  },
+];