@techbulls/encrypted-s3-store 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techbulls/encrypted-s3-store",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,11 @@
   "keywords": [],
   "author": "Aditya Chaphekar <aditya.chaphekar@techbulls.com>",
   "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "licenses": [
     {
       "type": "Apache-2.0",

package/.prettierignore

@@ -1,3 +0,0 @@
-dist
-node_modules
-pnpm-lock.yaml

package/.prettierrc

@@ -1,7 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "es5",
-  "printWidth": 100
-}

package/eslint.config.js

@@ -1,23 +0,0 @@
-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',
-      },
-    },
-  },
-];

package/src/client.ts

@@ -1,297 +0,0 @@
-/**
- * @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, S3Client } from '@aws-sdk/client-s3';
-import { SdkStream } from '@aws-sdk/types';
-import { IDownload, IUpload, ModeType } from './types.js';
-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 {
-  /** @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 = 'aes-256-gcm';
-
-  /** @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) {
-    this.client = client;
-    const envEncryptionKey = process.env.ENCRYPTION_KEY;
-    if (!key && !envEncryptionKey) {
-      throw new Error('Encryption key not provided.');
-    }
-    this.key = (key || envEncryptionKey) as string;
-
-    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: IUpload) {
-    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: Buffer;
-    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: IDownload) {
-    /** 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 as SdkStream<Readable>),
-        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 as SdkStream<Readable>),
-        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 as SdkStream<Readable>).pipe(decipher);
-
-    return {
-      Body: decryptedStream,
-      ContentType: response.ContentType,
-      ContentLength: response.ContentLength,
-      Metadata: response.Metadata,
-    };
-  }
-}

package/src/index.ts

@@ -1,26 +0,0 @@
-/**
- * @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';

package/src/types.ts

@@ -1,59 +0,0 @@
-/**
- * @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;
-}

package/src/utils.ts

@@ -1,57 +0,0 @@
-/**
- * @fileoverview Utility functions for encryption key derivation.
- *
- * @author Aditya Chaphekar <aditya.chaphekar@techbulls.com>
- * @license Apache-2.0
- */
-import { scrypt, ScryptOptions } from 'node:crypto';
-import { promisify } from 'node:util';
-
-/** Promisified version of Node.js scrypt function */
-const scryptAsync = promisify<string | Buffer, Buffer, number, ScryptOptions, Buffer>(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: string, salt: Buffer): Promise<Buffer> => {
-  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 as Buffer;
-};

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "Node",
-    "outDir": "dist",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}