@dotenvage/node 0.1.5

package/README.md

@@ -0,0 +1,337 @@
+# @dotenvage/node
+
+[![npm version](https://badge.fury.io/js/%40dotenvage%2Fnode.svg)](https://www.npmjs.com/package/@dotenvage/node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/dataroadinc/dotenvage/blob/main/LICENSE)
+
+Node.js bindings for
+[dotenvage](https://github.com/dataroadinc/dotenvage) - **Dotenv with
+age encryption**.
+
+## Features
+
+- 🔒 **Encrypt secrets in `.env` files** - Safely commit encrypted
+  secrets to version control
+- 📦 **Native performance** - Built with NAPI-RS for fast Rust
+  performance
+- 🔄 **Auto-detection** - Automatically identifies which keys should
+  be encrypted
+- 🌳 **File layering** - Multiple `.env*` files with automatic
+  precedence
+- 💻 **CLI support** - Includes `dotenvage` command-line tool
+- 📝 **TypeScript support** - Full TypeScript definitions included
+
+## Installation
+
+```bash
+npm install @dotenvage/node
+```
+
+## Quick Start
+
+### Basic Usage (Like dotenv)
+
+```typescript
+import * as dotenvage from "@dotenvage/node";
+
+// Load encrypted .env files into process.env
+const loader = dotenvage.JsEnvLoaderNew();
+loader.load(); // Mutates process.env (like dotenv.config())
+
+// Now access variables
+const apiKey = process.env.API_KEY;
+const dbUrl = process.env.DATABASE_URL;
+```
+
+### Get Variables as Object (Non-mutating)
+
+```typescript
+import * as dotenvage from "@dotenvage/node";
+
+const loader = dotenvage.JsEnvLoaderNew();
+const env = loader.getAllVariables(); // Returns Record<string, string>
+
+// Use without modifying process.env
+console.log(env.API_KEY);
+console.log(env.DATABASE_URL);
+```
+
+### Encrypt and Decrypt Values
+
+```typescript
+import * as dotenvage from "@dotenvage/node";
+
+// Generate a new key pair
+const manager = dotenvage.JsSecretManagerGenerate();
+const publicKey = manager.publicKeyString(); // Share this public key
+
+// Encrypt a secret
+const secret = "sk_live_abc123";
+const encrypted = manager.encryptValue(secret);
+// Returns: "ENC[AGE:b64:...]"
+
+// Decrypt it back
+const decrypted = manager.decryptValue(encrypted);
+console.log(decrypted === secret); // true
+```
+
+## API Reference
+
+### JsEnvLoader
+
+Loads and decrypts `.env` files.
+
+#### `JsEnvLoaderNew(): JsEnvLoader`
+
+Creates a new loader with a default SecretManager.
+
+```typescript
+const loader = dotenvage.JsEnvLoaderNew();
+```
+
+#### `load(): void`
+
+Loads `.env` files from the current directory into `process.env`.
+
+```typescript
+loader.load(); // Sets variables in process.env
+```
+
+#### `loadFromDir(dir: string): void`
+
+Loads `.env` files from a specific directory.
+
+```typescript
+loader.loadFromDir("./config");
+```
+
+#### `getAllVariableNames(): string[]`
+
+Gets all variable names from all loaded `.env` files (without loading
+into environment).
+
+```typescript
+const names = loader.getAllVariableNames();
+console.log(names); // ["API_KEY", "DATABASE_URL", ...]
+```
+
+#### `getAllVariables(): Record<string, string>`
+
+Gets all environment variables as an object (decrypted). Note: This
+loads variables into the process environment first.
+
+```typescript
+const env = loader.getAllVariables();
+console.log(env.API_KEY);
+```
+
+#### `resolveEnvPaths(dir: string): string[]`
+
+Computes the ordered list of env file paths that would be loaded.
+
+```typescript
+const paths = loader.resolveEnvPaths(".");
+console.log(paths); // [".env", ".env.local", ...]
+```
+
+### JsSecretManager
+
+Manages encryption and decryption of secrets.
+
+#### `JsSecretManagerGenerate(): JsSecretManager`
+
+Generates a new random encryption key pair.
+
+```typescript
+const manager = dotenvage.JsSecretManagerGenerate();
+```
+
+#### `JsSecretManagerNew(): JsSecretManager`
+
+Creates a SecretManager by loading the key from standard locations:
+
+1. `DOTENVAGE_AGE_KEY` environment variable
+2. `AGE_KEY` environment variable
+3. `EKG_AGE_KEY` environment variable
+4. Key file at `~/.local/state/dotenvage/dotenvage.key`
+
+```typescript
+const manager = dotenvage.JsSecretManagerNew();
+```
+
+#### `publicKeyString(): string`
+
+Gets the public key as a string (starts with `age1`).
+
+```typescript
+const publicKey = manager.publicKeyString();
+```
+
+#### `encryptValue(plaintext: string): string`
+
+Encrypts a plaintext value.
+
+```typescript
+const encrypted = manager.encryptValue("secret");
+```
+
+#### `decryptValue(value: string): string`
+
+Decrypts a value if it's encrypted; otherwise returns it unchanged.
+
+```typescript
+const decrypted = manager.decryptValue(encrypted);
+```
+
+#### `isEncrypted(value: string): boolean`
+
+Checks if a value is in a recognized encrypted format.
+
+```typescript
+const isEncrypted = manager.isEncrypted("ENC[AGE:b64:...]");
+```
+
+### Utility Functions
+
+#### `shouldEncrypt(key: string): boolean`
+
+Checks if a key name should be encrypted based on auto-detection
+patterns.
+
+```typescript
+dotenvage.shouldEncrypt("API_KEY"); // true
+dotenvage.shouldEncrypt("PORT"); // false
+```
+
+## CLI Usage
+
+The package includes a `dotenvage` CLI command:
+
+```bash
+npx dotenvage list
+npx dotenvage get API_KEY
+npx dotenvage dump --export
+```
+
+See the
+[main dotenvage README](https://github.com/dataroadinc/dotenvage#usage)
+for full CLI documentation.
+
+## Next.js Integration
+
+For Next.js applications, use the dedicated integration utilities:
+
+```typescript
+// In next.config.mjs
+import { loadEnv } from "@dotenvage/node/nextjs";
+loadEnv();
+```
+
+Or use the pre-initialization loader to ensure environment variables
+are available for Edge Runtime (middleware):
+
+```json
+{
+  "scripts": {
+    "dev": "node -r @dotenvage/node/nextjs/preinit node_modules/.bin/next dev"
+  }
+}
+```
+
+See [`nextjs/README.md`](./nextjs/README.md) for complete Next.js
+integration documentation.
+
+## TypeScript Examples
+
+See the `examples/` directory for TypeScript examples:
+
+- `load-env.ts` - Loading environment variables
+- `encrypt-decrypt.ts` - Encryption and decryption
+- `app-config.ts` - Type-safe application configuration
+- `auto-encrypt.ts` - Auto-detection patterns
+- `nextjs-config.ts` - Basic Next.js usage example
+
+## File Layering
+
+dotenvage supports automatic file layering with precedence:
+
+1. `.env` - Base configuration
+2. `.env.<ENV>` - Environment-specific (e.g., `.env.production`)
+3. `.env.<ENV>.<OS>` - OS-specific (e.g., `.env.production.linux`)
+4. `.env.<ENV>.<OS>.<ARCH>` - Architecture-specific
+5. `.env.<ENV>.<OS>.<ARCH>.<USER>` - User-specific overrides
+
+Files are loaded in specificity order - more specific files override
+less specific ones.
+
+## Key Management
+
+### Setting the Encryption Key
+
+Set one of these environment variables:
+
+```bash
+export DOTENVAGE_AGE_KEY="AGE-SECRET-KEY-1..."
+export AGE_KEY="AGE-SECRET-KEY-1..."
+export EKG_AGE_KEY="AGE-SECRET-KEY-1..."
+```
+
+### Generating a Key
+
+```typescript
+const manager = dotenvage.JsSecretManagerGenerate();
+const publicKey = manager.publicKeyString();
+console.log(`Public key: ${publicKey}`);
+console.log(`Set: export DOTENVAGE_AGE_KEY="<private-key>"`);
+```
+
+Or use the CLI:
+
+```bash
+npx dotenvage keygen
+```
+
+## Comparison with dotenv
+
+| Feature              | dotenv | @dotenvage/node |
+| -------------------- | ------ | --------------- |
+| Load `.env` files    | ✅     | ✅              |
+| Mutate `process.env` | ✅     | ✅              |
+| Encrypt secrets      | ❌     | ✅              |
+| Commit to git safely | ❌     | ✅              |
+| File layering        | ❌     | ✅              |
+| Auto-detection       | ❌     | ✅              |
+| Native performance   | ❌     | ✅ (Rust)       |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Valid age encryption key (set via environment variable or key file)
+
+## Building from Source
+
+From the `npm/` directory:
+
+```bash
+cd npm
+npm install
+npm run build
+```
+
+Or from the project root:
+
+```bash
+npm run npm:install
+npm run npm:build
+```
+
+## License
+
+MIT - See
+[LICENSE](https://github.com/dataroadinc/dotenvage/blob/main/LICENSE)
+
+## Links
+
+- [GitHub Repository](https://github.com/dataroadinc/dotenvage)
+- [Rust Crate](https://crates.io/crates/dotenvage)
+- [Rust Documentation](https://docs.rs/dotenvage)
+- [Main README](https://github.com/dataroadinc/dotenvage#readme)

package/bin/dotenvage-next.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Next.js wrapper for dotenvage - loads encrypted environment variables before Next.js starts.
+ *
+ * This bin script allows users to call dotenvage-next directly without specifying the full path.
+ *
+ * Usage:
+ *   pnpm exec dotenvage-next dev
+ *   pnpm exec dotenvage-next build
+ *
+ * Or via package.json scripts:
+ *   "dev": "dotenvage-next dev"
+ *   "build": "dotenvage-next build"
+ */
+
+// Import and execute the wrapper script
+// The wrapper.mjs file uses top-level await and has side effects, so importing it will execute it
+import("../nextjs/wrapper.mjs");

package/bin/dotenvage.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+/**
+ * Node.js CLI wrapper for dotenvage
+ *
+ * This wrapper attempts to use the native Rust binary if available,
+ * otherwise falls back to using the NAPI bindings to implement CLI functionality.
+ */
+
+const { existsSync } = require("fs");
+const { join } = require("path");
+const { spawn, execSync } = require("child_process");
+const { platform, arch } = require("os");
+
+// Determine the binary name based on platform
+function getBinaryName() {
+  const plat = platform();
+  const architecture = arch();
+
+  // Map Node.js arch to Rust target arch
+  const archMap = {
+    x64: "x86_64",
+    arm64: "aarch64",
+    ia32: "i686",
+  };
+
+  const rustArch = archMap[architecture] || architecture;
+
+  if (plat === "win32") {
+    return `dotenvage-${rustArch}-pc-windows-msvc.exe`;
+  } else if (plat === "darwin") {
+    return `dotenvage-${rustArch}-apple-darwin`;
+  } else {
+    return `dotenvage-${rustArch}-unknown-linux-gnu`;
+  }
+}
+
+// Try to find the native binary
+function findNativeBinary() {
+  // Check in common locations
+  const possiblePaths = [
+    // In the npm package directory
+    join(__dirname, "..", "bin", getBinaryName()),
+    // In node_modules/.bin
+    join(__dirname, "..", "..", "..", "bin", getBinaryName()),
+    // Global installation
+    join(
+      process.env.HOME || process.env.USERPROFILE || "",
+      ".cargo",
+      "bin",
+      "dotenvage"
+    ),
+    join(
+      process.env.HOME || process.env.USERPROFILE || "",
+      ".local",
+      "bin",
+      "dotenvage"
+    ),
+    // PATH
+    "dotenvage",
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      if (path === "dotenvage") {
+        // Check if it's in PATH
+        execSync(`which ${path}`, { stdio: "ignore" });
+        return path;
+      } else if (existsSync(path)) {
+        return path;
+      }
+    } catch (e) {
+      // Continue searching
+    }
+  }
+
+  return null;
+}
+
+// Fallback to NAPI implementation
+function useNapiImplementation() {
+  try {
+    const dotenvage = require("../index.js");
+
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const command = args[0];
+
+    switch (command) {
+      case "keygen":
+      case "gen":
+        {
+          const manager = dotenvage.JsSecretManagerGenerate();
+          console.log(`✓ Private key generated`);
+          console.log(
+            `Public recipient: ${manager.publicKeyString()}`
+          );
+          console.log(
+            `Note: Use DOTENVAGE_AGE_KEY or AGE_KEY environment variable to set the key`
+          );
+        }
+        break;
+
+      case "get":
+        {
+          const key = args[1];
+          if (!key) {
+            console.error("Error: key name required");
+            process.exit(1);
+          }
+
+          const loader = dotenvage.JsEnvLoaderNew();
+          loader.load();
+
+          const value = process.env[key];
+          if (value === undefined) {
+            console.error(
+              `Error: key '${key}' not found in any .env* file`
+            );
+            process.exit(1);
+          }
+
+          console.log(value);
+        }
+        break;
+
+      case "list":
+        {
+          const verbose =
+            args.includes("--verbose") || args.includes("-v");
+          const json = args.includes("--json");
+          const plain = args.includes("--plain");
+          const fileIndex = args.indexOf("--file");
+          const file = fileIndex >= 0 ? args[fileIndex + 1] : null;
+
+          const loader = dotenvage.JsEnvLoaderNew();
+          let names;
+
+          if (file) {
+            loader.loadFromDir(process.cwd());
+            names = loader.getAllVariableNamesFromDir(process.cwd());
+          } else {
+            loader.load();
+            names = loader.getAllVariableNames();
+          }
+
+          if (json) {
+            const output = {};
+            for (const name of names) {
+              const value = process.env[name];
+              if (value) {
+                output[name] = verbose
+                  ? { value, encrypted: false }
+                  : { encrypted: false };
+              }
+            }
+            console.log(JSON.stringify(output, null, 2));
+          } else {
+            for (const name of names) {
+              if (verbose) {
+                const value = process.env[name];
+                const lockIcon = "  "; // Can't easily detect encryption without manager
+                console.log(`${lockIcon} ${name} = ${value}`);
+              } else if (plain) {
+                console.log(name);
+              } else {
+                console.log(`  ${name}`);
+              }
+            }
+          }
+        }
+        break;
+
+      case "dump":
+        {
+          const exportFlag =
+            args.includes("--export") || args.includes("-e");
+          const fileIndex = args.indexOf("--file");
+          const file = fileIndex >= 0 ? args[fileIndex + 1] : null;
+
+          const loader = dotenvage.JsEnvLoaderNew();
+
+          if (file) {
+            loader.loadFromDir(process.cwd());
+          } else {
+            loader.load();
+          }
+
+          const vars = loader.getAllVariables();
+          const prefix = exportFlag ? "export " : "";
+
+          for (const [key, value] of Object.entries(vars)) {
+            // Simple escaping for values
+            const needsQuotes =
+              value.includes(" ") ||
+              value.includes("$") ||
+              value.includes("`");
+            if (needsQuotes) {
+              const escaped = value
+                .replace(/"/g, '\\"')
+                .replace(/\$/g, "\\$");
+              console.log(`${prefix}${key}="${escaped}"`);
+            } else {
+              console.log(`${prefix}${key}=${value}`);
+            }
+          }
+        }
+        break;
+
+      default:
+        console.error(`Error: Unknown command '${command}'`);
+        console.error(`
+Usage: dotenvage <command> [options]
+
+Commands:
+  keygen, gen          Generate a new encryption key pair
+  get <key>            Get a decrypted secret value
+  list                 List environment variables
+  dump                 Dump all decrypted env vars
+
+Note: This is a limited implementation using NAPI bindings.
+For full functionality, install the native Rust binary:
+  cargo install dotenvage
+        `);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error("Error:", error.message);
+    console.error(`
+Note: Native bindings not available. Install the native Rust binary:
+  cargo install dotenvage
+    `);
+    process.exit(1);
+  }
+}
+
+// Main entry point
+function main() {
+  const binary = findNativeBinary();
+
+  if (binary) {
+    // Use native binary
+    const child = spawn(binary, process.argv.slice(2), {
+      stdio: "inherit",
+      shell: false,
+    });
+
+    child.on("error", (error) => {
+      console.error(`Error running dotenvage: ${error.message}`);
+      console.error("Falling back to NAPI implementation...");
+      useNapiImplementation();
+    });
+
+    child.on("exit", (code) => {
+      process.exit(code || 0);
+    });
+  } else {
+    // Fallback to NAPI implementation
+    useNapiImplementation();
+  }
+}
+
+if (require.main === module) {
+  main();
+}