@bhargavratnala/build-env 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bhargav Ratnala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# 🔐 Build-Env
+
+**Secure runtime environment variables for frontend applications — without build-time replacement.**
+
+`build-env` allows frontend apps (React, Vite, etc.) to **load environment variables at runtime** using encrypted configuration, enabling **one build for multiple environments**.
+
+---
+
+## 🚀 Problem
+
+Frontend frameworks normally:
+- Replace env variables **at build time**
+- Require **rebuilding for each environment**
+- Expose values directly in the JS bundle
+
+Browsers cannot read `.env` files at runtime.
+
+---
+
+## ✅ Solution
+
+`build-env` introduces a **secure runtime env system** using encryption:
+
+- 🔒 Encrypted env config
+- ⚙️ Runtime loading (post-build)
+- 🔁 No rebuilds per environment
+- 🛡️ No plaintext env values in bundle
+
+---
+
+## 🧠 How It Works
+
+1. Generate a **public/private key pair**
+2. Store the **private key** securely in `.env`
+3. Encrypt environment variables into a config file
+4. Load & decrypt envs **at runtime**
+5. Access variables using a `get()` method
+
+---
+
+## 📦 Installation
+
+```bash
+npm install build-env
+```
+
+## 🪜 Step-by-Step Usage
+
+Step 1: Generate Encryption Keys
+
+```bash
+npx build-env generate
+```
+
+
+This generates:
+```text
+private_key        # Private key (DO NOT COMMIT)
+public_key.pem     # Public key used for encryption
+```
+
+## Step 2: Store Private Key in .env
+
+Add the private key and config path to your .env file:
+
+```env
+VITE_PRIVATE_KEY=your_private_key_here
+VITE_BUILD_ENV_CONFIG=/build-env.config
+```
+
+
+> ⚠️ Never commit the private_key file or private key value.
+
+## Step 3: Build Encrypted Environment Config
+
+```bash
+npx build-env build
+```
+
+
+This command:
+
+Encrypts all environment variables
+
+Generates an encrypted config file
+
+Saves it inside the `public/directory`
+
+Example:
+
+public/build-env.config
+
+## Step 4: Load Environment Variables at Runtime
+
+Add this code at the root of your application (before rendering the app):
+
+```js
+const [ready, setReady] = useState(false);
+
+useEffect(() => {
+  async function init() {
+    await loadEncryptedEnv(
+      import.meta.env.VITE_PRIVATE_KEY,
+      import.meta.env.VITE_BUILD_ENV_CONFIG
+    );
+    setReady(true);
+  }
+
+  init();
+}, []);
+```
+
+Ensure the app renders only after envs are loaded:
+
+```js
+if (!ready) return null;
+```
+
+## Step 5: Access Environment Variables
+
+Use the get method provided by build-env anywhere in your app:
+
+```js
+import { get } from "build-env";
+
+const apiUrl = get("API_URL");
+const appMode = get("APP_MODE");
+```
+
+✔ No process.env
+✔ No build-time replacement
+
+
+## 🧩 Supported Frameworks
+
+✅ React (CRA, Vite)
+
+✅ Vite-based frameworks
+
+✅ Any SPA that supports runtime JavaScript loading
+
+## 🔒 Security Notes
+
+All environment variables are encrypted
+
+The private key is never shipped in the build
+
+Suitable for:
+- API URLs
+- Feature flags
+- Public keys
+- Environment identifiers
+
+> ❌ Do not store secrets such as database credentials or private tokens.
+
+## 🏗️ Deployment Workflow
+```mermaid
+graph TD;
+  A[Build once] --> B[Deploy static assets]
+  B --> C[Set PRIVATE_KEY in environment]
+  C --> D[Serve encrypted config]
+  D --> E[App decrypts variables at runtime]
+```
+
+## Works well with:
+
+- Docker
+- Kubernetes
+- Netlify
+- Vercel
+- Nginx / CDN hosting
+
+## 🎯 When to Use build-env
+
+Use build-env if you want:
+- A single frontend build
+- Runtime environment configuration
+- No rebuilds per environment
+- Secure environment variable handling
+
+## 📄 License
+
+MIT

package/bin/build-env.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { generateKeyPair, encryptEnv } from "../src/crypto.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const [command, inputFile] = process.argv.slice(2);
+
+function usage() {
+  console.log(`
+build-env CLI
+
+Usage:
+  build-env generate
+  build-env build [.env]
+
+Examples:
+  build-env generate
+  build-env build .env
+`);
+}
+
+export function saveKeyPair(privateKey, publicKey) {
+  fs.writeFileSync("private_key", privateKey);
+  fs.writeFileSync("public_key.pem", publicKey);
+}
+
+export function readPublicKey() {
+  return fs.readFileSync("public_key.pem", "utf8");
+}
+
+switch (command) {
+  case "generate": {
+    const { privateKey, publicKey } = generateKeyPair();
+    saveKeyPair(privateKey, publicKey);
+    console.log("✅ RSA key pair generated");
+    break;
+  }
+
+  case "build": {
+    const envFile = inputFile || "build.env";
+    if (!fs.existsSync(envFile)) {
+      console.error(`❌ File not found: ${envFile}`);
+      process.exit(1);
+    }
+
+    const envText = fs.readFileSync(envFile, "utf8");
+    const publicKeyPem = readPublicKey();
+    const encrypted = encryptEnv(envText, publicKeyPem);
+    fs.writeFileSync("public/build.env.json", encrypted);
+
+    console.log("✅ Encrypted env written to public/build.env.json");
+    break;
+  }
+
+  default:
+    usage();
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@bhargavratnala/build-env",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "bin": {
+    "build-env": "./bin/build-env.js"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "node-forge": "^1.3.3"
+  }
+}

package/src/crypto.js

@@ -0,0 +1,79 @@
+import forge from "node-forge";
+
+/* ---------- KEY MANAGEMENT ---------- */
+
+export function generateKeyPair() {
+  const { privateKey, publicKey } = forge.pki.rsa.generateKeyPair({ bits: 2048, e: 0x10001 });
+  const asn1 = forge.pki.privateKeyToAsn1(privateKey);
+  const der = forge.asn1.toDer(asn1).getBytes();
+  const base64Key = forge.util.encode64(der);
+  return { privateKey: base64Key, publicKey: forge.pki.publicKeyToPem(publicKey) };
+}
+
+export function loadPublicKey(publicKeyPem) {
+  return forge.pki.publicKeyFromPem(
+    publicKeyPem
+  );
+}
+
+export function loadPrivateKey(privateKeyValue) {
+  const der = forge.util.decode64(privateKeyValue);
+  const asn1 = forge.asn1.fromDer(der);
+  const privateKey = forge.pki.privateKeyFromAsn1(asn1);
+  return privateKey;
+}
+
+/* ---------- HYBRID ENCRYPTION ---------- */
+
+export function encryptEnv(envText, publicKeyPem) {
+  const publicKey = loadPublicKey(publicKeyPem);
+
+  // AES key
+  const aesKey = forge.random.getBytesSync(32);
+  const iv = forge.random.getBytesSync(12);
+
+  // Encrypt env using AES-GCM
+  const cipher = forge.cipher.createCipher("AES-GCM", aesKey);
+  cipher.start({ iv });
+  cipher.update(forge.util.createBuffer(envText, "utf8"));
+  cipher.finish();
+
+  const encryptedEnv = cipher.output.getBytes();
+  const tag = cipher.mode.tag.getBytes();
+
+  // Encrypt AES key using RSA
+  const encryptedKey = publicKey.encrypt(aesKey, "RSA-OAEP", {
+    md: forge.md.sha256.create(),
+  });
+
+  return JSON.stringify({
+    key: forge.util.encode64(encryptedKey),
+    iv: forge.util.encode64(iv),
+    tag: forge.util.encode64(tag),
+    data: forge.util.encode64(encryptedEnv),
+  });
+}
+
+export function decryptEnv(privateKeyValue, payload) {
+  const privateKey = loadPrivateKey(privateKeyValue);
+  
+  const parsed = JSON.parse(payload);
+
+  const aesKey = privateKey.decrypt(
+    forge.util.decode64(parsed.key),
+    "RSA-OAEP",
+    { md: forge.md.sha256.create() }
+  );
+
+  const decipher = forge.cipher.createDecipher("AES-GCM", aesKey);
+  decipher.start({
+    iv: forge.util.decode64(parsed.iv),
+    tag: forge.util.decode64(parsed.tag),
+  });
+  decipher.update(
+    forge.util.createBuffer(forge.util.decode64(parsed.data))
+  );
+  decipher.finish();
+
+  return decipher.output.toString("utf8");
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { loadEncryptedEnv } from "./loader.js";
+export { get, has, getEnvObject } from "./store.js";

package/src/loader.js

@@ -0,0 +1,24 @@
+import { decryptEnv } from "./crypto.js";
+import { setEnvObject } from "./store.js";
+
+export async function loadEncryptedEnv(privateKey, filename = "build.env.json") {
+  const config = await fetch(filename).then((res) => res.text());
+  const decrypted = decryptEnv(privateKey, config);
+
+  const envObject = Object.create(null);
+
+  decrypted.split("\n").forEach((line) => {
+    if (!line || line.startsWith("#")) return;
+
+    const idx = line.indexOf("=");
+    if (idx === -1) return;
+
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+
+    envObject[key] = value;
+  });
+
+  setEnvObject(envObject);
+  return envObject;
+}

package/src/store.js

@@ -0,0 +1,17 @@
+let envStore = Object.create(null);
+
+export function setEnvObject(obj) {
+  envStore = Object.freeze({ ...obj });
+}
+
+export function getEnvObject() {
+  return envStore;
+}
+
+export function get(key, defaultValue = undefined) {
+  return envStore[key] ?? defaultValue;
+}
+
+export function has(key) {
+  return Object.prototype.hasOwnProperty.call(envStore, key);
+}