ultra-secure-transfer 🔐

Production-ready, isomorphic npm package combining Hybrid Encryption (RSA + AES-256-GCM). Built for transmitting highly sensitive JSON documents and streaming massive binary files securely between frontends and backends.

ultra-secure-transfer seamlessly operates in the Browser (utilizing the native, hardware-accelerated WebCrypto API) and Node.js (utilizing the crypto module).

🚀 Features

• Hybrid Security: Combine the asymmetric security of RSA for keys and the supersonic speed of AES-256-GCM for payload payloads.
• Isomorphic Architecture: The exact same API surface works in the Browser and Backend.
• Double-Layer Obfuscation: For JSON payloads, a strict 6-step architecture involves AES( RSA(Key2) + AES(Payload + Key1) ) split by random fragment lengths and joined using a custom separator.
• Production File Streaming: Avoid massive memory crashes. Safely dynamically stream 10MB to 100GB+ files chunk-by-chunk securely.
• Built-in CLI Key Generator: Generate .env ready 2048-bit RSA keys easily.

📦 Installation

npm install ultra-secure-transfer

🛠 Usage Overview

1. Generating Keys

You only need to generate RSA Keys once. Store the Private Key ONLY on the server, and the Public Key ONLY on the client. Never expose your Private Key.

We provide a built-in CLI to generate a .env.local file containing strictly formatted keys:

npx generate-keys

2. Standard JSON Payload Transfer

Using the standard data transfer architecture.

Frontend (Encryption Layer):

import { encryptData } from "ultra-secure-transfer";

const data = { user: "Alice", action: "TRANSFER", amount: 999.0 };

// Your shared configuration (these act as the Salt / Base Symmetric Keys)
const separator = "||--MY--APP--||";
const encryptionKey1 = "client-base-secret-xyz";
const encryptionKey2 = "dynamically-generated-secret-per-session";

const securePayload = await encryptData(
  data,
  separator,
  encryptionKey1,
  encryptionKey2, // Will be encrypted using the RSA Public Key automatically
  process.env.RSA_PUBLIC_KEY,
);

// Transmit `securePayload` across the network via fetch/axios!

Backend (Decryption Layer):

import { decryptData } from "ultra-secure-transfer";

// Receive `securePayload` from the Express req.body / API Gateway
const originalData = await decryptData(
  securePayload,
  separator,
  encryptionKey1,
  null, // Alternatively, pass the exact encryptionKey2 here if asserting absolute integrity.
  process.env.RSA_PRIVATE_KEY,
);

console.log(originalData); // Output: { user: "Alice", action: "TRANSFER", amount: 999.00 }

3. Scalable Large File (Chunk) Streaming 📹

Streaming massive files without saving them to RAM helps your backend handle tens of thousands of simultaneous file uploads. Each 1MB file block is individually authenticated seamlessly.

Frontend (Reading & Encrypting File):

import {
  generateFileTransferKey,
  encryptFileChunk,
} from "ultra-secure-transfer";

const file = document.getElementById("fileInput").files[0];

// 1. Locally generate a true Native AES Key dynamically and wrap it using RSA
const { aesKey, encryptedKeyBase64 } = await generateFileTransferKey(
  process.env.RSA_PUBLIC_KEY,
);

// Send `encryptedKeyBase64` to your backend so it knows what AES key will be used for the upcoming streaming chunks!

// 2. Stream chunk by chunk natively
const CHUNK_SIZE = 1024 * 1024; // 1 MB chunks
const totalChunks = Math.ceil(file.size / CHUNK_SIZE);

for (let i = 0; i < totalChunks; i++) {
  const blob = file.slice(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE);
  const chunkBuffer = await blob.arrayBuffer();

  // 3. Encrypt the binary block with AES-256-GCM.
  // This outputs an entirely unique, unpredictable { iv, authTag, ciphertext } structure.
  const secureChunk = await encryptFileChunk(chunkBuffer, aesKey);

  // 4. Send `secureChunk` exactly down the network socket/HTTP Route!
}

Backend (Decryption & Writing to Disk):

import { unwrapFileTransferKey, decryptFileChunk } from "ultra-secure-transfer";
import fs from "fs";

// 1. Unwrap the dynamic AES key using the Backend's RSA Private Key!
const aesKey = await unwrapFileTransferKey(
  encryptedKeyBase64,
  process.env.RSA_PRIVATE_KEY,
);

// 2. Iterate inbound `secureChunk`s received from POST Requests
const decryptedChunkBuffer = await decryptFileChunk(
  incomingPayload.iv,
  incomingPayload.authTag,
  incomingPayload.ciphertext,
  aesKey,
);

// 3. Directly dump binary onto disk (Storage Level, Network Level, Or S3 Layer!)
fs.appendFileSync("uploaded_secure_video.mp4", decryptedChunkBuffer);

🔒 Security Posture

• No secrets are hardcoded in the codebase.
• The crypto.subtle API guarantees browser cryptographical randomness and prevents polyfill interception.
• Double-Pass AES-256-GCM for standard JSON adds an invisible layer of custom fragment obfuscation blocking all common plaintext scanning hooks.
• Unique Initialization Vector (IV) generation on every single chunk stream completely disrupts identical-byte prediction analysis.

⚖️ License

MIT