@akshxy/envgit 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,128 @@
+# envgit
+
+Encrypted per-project environment variable manager. Store secrets safely alongside your code — encrypted at rest, never in plaintext.
+
+```
+npm install -g @akshxy/envgit
+```
+
+## Why
+
+`.env` files get committed by accident. `envgit` keeps your secrets encrypted in `.envgit/` so you can safely commit them to git and share them with your team — only people with the key can decrypt them.
+
+## Quick start
+
+```bash
+# 1. Initialize in your project
+envgit init
+
+# 2. Set some variables
+envgit set API_KEY=abc123 DB_PASS=secret
+
+# 3. Commit the encrypted store (not the key!)
+git add .envgit/
+git commit -m "add encrypted env"
+
+# 4. Share your key with teammates
+envgit keygen --show
+# → teammate runs: envgit keygen --set <key>
+
+# 5. Write .env when you need it locally
+envgit unpack dev
+```
+
+## Commands
+
+### Key management
+
+| Command | Description |
+|---------|-------------|
+| `envgit init` | Initialize in current project, generates key |
+| `envgit keygen` | Generate a new key and save it |
+| `envgit keygen --show` | Print current key for sharing with teammates |
+| `envgit keygen --set <key>` | Save a key received from a teammate |
+| `envgit rotate-key` | Generate new key, re-encrypt all environments |
+| `envgit verify` | Check all environments decrypt correctly |
+
+### Variables
+
+| Command | Description |
+|---------|-------------|
+| `envgit set KEY=VALUE ...` | Set one or more variables |
+| `envgit get KEY` | Print a single value |
+| `envgit delete KEY` | Remove a variable |
+| `envgit rename OLD NEW` | Rename a variable |
+| `envgit list` | List all keys in active environment |
+| `envgit list --show-values` | List keys and values |
+
+### Environments
+
+| Command | Description |
+|---------|-------------|
+| `envgit envs` | List all environments with variable counts |
+| `envgit add-env <name>` | Create a new environment |
+| `envgit unpack <env>` | Decrypt env and write `.env` file |
+| `envgit copy KEY --from dev --to prod` | Copy a variable between environments |
+| `envgit diff dev prod` | Show differences between two environments |
+| `envgit diff dev prod --show-values` | Include values in diff |
+
+### Export & run
+
+| Command | Description |
+|---------|-------------|
+| `envgit export` | Print as `KEY=VALUE` lines (pipeable) |
+| `envgit export --format json` | Print as JSON |
+| `envgit export --format shell` | Print as `export KEY="VALUE"` (eval-able) |
+| `envgit run -- node server.js` | Run a command with env vars injected |
+| `envgit import --file .env.local` | Encrypt an existing `.env` file |
+
+### Status
+
+| Command | Description |
+|---------|-------------|
+| `envgit status` | Show project, active env, key source, .env state |
+
+## All options support `--env <name>`
+
+Most commands default to the active environment. Pass `--env` to target a specific one:
+
+```bash
+envgit set API_KEY=prod-key --env prod
+envgit list --env staging
+envgit export --env prod --format json
+```
+
+## Team workflow
+
+```bash
+# Developer A (project owner)
+envgit init
+envgit set DB_URL=postgres://... API_KEY=...
+git add .envgit/ && git commit -m "encrypted env"
+envgit keygen --show   # share this key securely with teammates
+
+# Developer B (teammate)
+git clone <repo>
+envgit keygen --set <key-from-teammate>
+envgit unpack dev      # writes .env
+```
+
+## Security
+
+- **AES-256-GCM** — authenticated encryption, tamper-proof
+- **32-byte random key** from OS cryptographic RNG
+- **Fresh random IV** per encryption — same value encrypts differently each time
+- **Key file locked to `0o600`** — unreadable by other users
+- **Permission check on load** — errors if `.envgit.key` is world-readable
+- **Key bytes zeroized** from memory immediately after use
+
+The key (`~/.envgit.key`) is gitignored automatically. Never commit it.
+
+## Environment variable
+
+Set `ENVGIT_KEY` instead of using a key file — useful in CI:
+
+```bash
+export ENVGIT_KEY=$(cat .envgit.key)
+envgit export --format shell | source /dev/stdin
+```

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@akshxy/envgit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Encrypted per-project environment variable manager",
   "type": "module",
   "bin": {
-    "envgit": "./bin/envgit.js"
+    "envgit": "bin/envgit.js"
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "README.md"
   ],
   "license": "MIT",
   "dependencies": {

package/src/commands/add-env.js

@@ -1,6 +1,7 @@
 import { requireProjectRoot, loadKey } from '../keystore.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { writeEncEnv } from '../enc.js';
+import { ok, fatal } from '../ui.js';
 
 export async function addEnv(name) {
   const projectRoot = requireProjectRoot();
@@ -8,13 +9,12 @@ export async function addEnv(name) {
   const config = loadConfig(projectRoot);
 
   if (config.envs.includes(name)) {
-    console.error(`Error: Environment '${name}' already exists.`);
-    process.exit(1);
+    fatal(`Environment '${name}' already exists.`);
   }
 
   config.envs.push(name);
   saveConfig(projectRoot, config);
   writeEncEnv(projectRoot, name, key, {});
 
-  console.log(`Added environment '${name}'.`);
+  ok(`Added environment '${name}'`);
 }

package/src/commands/get.js

@@ -2,6 +2,7 @@ import { requireProjectRoot, loadKey } from '../keystore.js';
 import { resolveEnv } from '../config.js';
 import { readEncEnv } from '../enc.js';
 import { getCurrentEnv } from '../state.js';
+import { fatal, label } from '../ui.js';
 
 export async function get(key, options) {
   const projectRoot = requireProjectRoot();
@@ -11,8 +12,7 @@ export async function get(key, options) {
   const vars = readEncEnv(projectRoot, envName, encKey);
 
   if (!(key in vars)) {
-    console.error(`Error: Key '${key}' not found in [${envName}]`);
-    process.exit(1);
+    fatal(`Key '${key}' not found in ${label(envName)}`);
   }
 
   console.log(vars[key]);

package/src/commands/import.js

@@ -5,6 +5,7 @@ import { resolveEnv } from '../config.js';
 import { writeEncEnv } from '../enc.js';
 import { readEnvFile } from '../envfile.js';
 import { getCurrentEnv } from '../state.js';
+import { ok, fatal, label, dim } from '../ui.js';
 
 export async function importEnv(options) {
   const projectRoot = requireProjectRoot();
@@ -13,15 +14,12 @@ export async function importEnv(options) {
 
   const filePath = join(projectRoot, options.file);
   if (!existsSync(filePath)) {
-    console.error(`Error: File not found: ${options.file}`);
-    process.exit(1);
+    fatal(`File not found: ${options.file}`);
   }
 
   const vars = readEnvFile(filePath);
   const count = Object.keys(vars).length;
 
   writeEncEnv(projectRoot, envName, key, vars);
-  console.log(
-    `Imported ${count} variable${count !== 1 ? 's' : ''} from ${options.file} into [${envName}]`
-  );
+  ok(`Imported ${count} variable${count !== 1 ? 's' : ''} from ${dim(options.file)} into ${label(envName)}`);
 }

package/src/commands/init.js

@@ -1,10 +1,11 @@
 import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { randomUUID } from 'crypto';
 import { generateKey } from '../crypto.js';
-import { saveKey } from '../keystore.js';
+import { saveKey, globalKeyPath } from '../keystore.js';
 import { saveConfig, getEnvctlDir } from '../config.js';
 import { writeEncEnv } from '../enc.js';
-import { ok, warn, fatal, bold, dim, label } from '../ui.js';
+import { ok, fatal, bold, dim, label } from '../ui.js';
 
 export async function init(options) {
   const projectRoot = process.cwd();
@@ -15,18 +16,21 @@ export async function init(options) {
   }
 
   const defaultEnv = options.env;
+  const keyId = randomUUID();
 
   mkdirSync(envgitDir, { recursive: true });
 
-  const key = generateKey();
-  saveKey(projectRoot, key);
-
+  // Save config first (saveKey needs key_id from config)
   saveConfig(projectRoot, {
     version: 1,
     default_env: defaultEnv,
     envs: [defaultEnv],
+    key_id: keyId,
   });
 
+  const key = generateKey();
+  const keyPath = saveKey(projectRoot, key, keyId);
+
   writeEncEnv(projectRoot, defaultEnv, key, {});
 
   updateGitignore(projectRoot);
@@ -35,16 +39,19 @@ export async function init(options) {
   console.log(bold('envgit initialized'));
   console.log('');
   ok(`Default environment: ${label(defaultEnv)}`);
-  ok('Key saved to .envgit.key');
+  ok(`Key stored at ${dim(keyPath)}`);
   console.log('');
-  console.log(dim('Keep .envgit.key secret and do not commit it.'));
   console.log(dim('Commit .envgit/ to share encrypted environments with your team.'));
+  console.log(dim('Your key never touches the repo — it lives only on your machine.'));
+  console.log('');
+  console.log(`Share your key with teammates:  ${bold('envgit keygen --show')}`);
+  console.log(`Teammates save it with:         ${bold('envgit keygen --set <key>')}`);
   console.log('');
 }
 
 function updateGitignore(projectRoot) {
   const gitignorePath = join(projectRoot, '.gitignore');
-  const entries = ['.env', '.envgit.key'];
+  const entries = ['.env'];
 
   let existing = '';
   if (existsSync(gitignorePath)) {

package/src/commands/keygen.js

@@ -1,21 +1,20 @@
 import { generateKey } from '../crypto.js';
-import { findProjectRoot, saveKey, loadKey } from '../keystore.js';
-import { ok, warn, bold, dim } from '../ui.js';
+import { findProjectRoot, saveKey, loadKey, globalKeyPath } from '../keystore.js';
+import { loadConfig } from '../config.js';
+import { ok, warn, fatal, bold, dim } from '../ui.js';
 
 export async function keygen(options) {
   const projectRoot = findProjectRoot();
 
   if (options.show) {
     if (!projectRoot) {
-      warn('No envgit project found — cannot show key.');
-      process.exit(1);
+      fatal('No envgit project found — cannot show key.');
     }
     let key;
     try {
       key = loadKey(projectRoot);
     } catch (e) {
-      warn(e.message);
-      process.exit(1);
+      fatal(e.message);
     }
     const hint = key.slice(0, 8);
     console.log('');
@@ -23,8 +22,8 @@ export async function keygen(options) {
     console.log(`  ${key}`);
     console.log('');
     console.log(dim(`Hint (first 8 chars): ${hint}`));
-    console.log(dim('Share this key with teammates via a secure channel (not git).'));
-    console.log(dim('They can save it with: envgit keygen --set <key>'));
+    console.log(dim('Share via a secure channel (not git, not chat).'));
+    console.log(dim('Teammate saves it with: envgit keygen --set <key>'));
     console.log('');
     return;
   }
@@ -33,16 +32,18 @@ export async function keygen(options) {
     const key = options.set;
     const decoded = Buffer.from(key, 'base64');
     if (decoded.length !== 32) {
-      warn(`Invalid key — must decode to exactly 32 bytes (got ${decoded.length}). Generate one with: envgit keygen`);
-      process.exit(1);
+      fatal(`Invalid key — must decode to exactly 32 bytes (got ${decoded.length}). Generate one with: envgit keygen`);
     }
     if (!projectRoot) {
-      warn('No envgit project found. Run envgit init first.');
-      process.exit(1);
+      fatal('No envgit project found. Run envgit init first, or clone a repo that uses envgit.');
     }
-    saveKey(projectRoot, key);
-    ok(`Key saved to .envgit.key`);
-    console.log(dim(`Hint: ${key.slice(0, 8)}`));
+    const keyPath = saveKey(projectRoot, key);
+    ok(`Key saved for this project`);
+    console.log(dim(`  Stored at: ${keyPath}`));
+    console.log(dim(`  Hint: ${key.slice(0, 8)}`));
+    console.log('');
+    console.log(dim('Run `envgit verify` to confirm it works.'));
+    console.log('');
     return;
   }
 
@@ -51,8 +52,9 @@ export async function keygen(options) {
   const hint = key.slice(0, 8);
 
   if (projectRoot) {
-    saveKey(projectRoot, key);
-    ok('New key generated and saved to .envgit.key');
+    const keyPath = saveKey(projectRoot, key);
+    ok(`New key generated`);
+    console.log(dim(`  Stored at: ${keyPath}`));
   } else {
     console.log('');
     console.log(bold('Generated key (no project found — not saved):'));
@@ -63,7 +65,7 @@ export async function keygen(options) {
   console.log(`  ${key}`);
   console.log('');
   console.log(dim(`Hint (first 8 chars): ${hint}`));
-  console.log(dim('Share this key with teammates via a secure channel (not git).'));
-  console.log(dim('They can save it with: envgit keygen --set <key>'));
+  console.log(dim('Share via a secure channel (not git, not chat).'));
+  console.log(dim('Teammate saves it with: envgit keygen --set <key>'));
   console.log('');
 }

package/src/commands/status.js

@@ -1,6 +1,6 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { requireProjectRoot } from '../keystore.js';
+import { requireProjectRoot, globalKeyPath } from '../keystore.js';
 import { loadConfig } from '../config.js';
 import { getCurrentEnv } from '../state.js';
 import chalk from 'chalk';
@@ -11,11 +11,19 @@ export async function status() {
   const config = loadConfig(projectRoot);
   const current = getCurrentEnv(projectRoot);
 
-  const keySource = process.env.ENVCTL_KEY
-    ? 'ENVCTL_KEY env var'
-    : existsSync(join(projectRoot, '.envgit.key'))
-    ? '.envgit.key'
-    : chalk.red('(not found)');
+  let keySource;
+  if (process.env.ENVGIT_KEY) {
+    keySource = chalk.green('ENVGIT_KEY') + dim(' (env var)');
+  } else if (config.key_id) {
+    const keyPath = globalKeyPath(config.key_id);
+    keySource = existsSync(keyPath)
+      ? chalk.green('~/.config/envgit/keys/') + dim(config.key_id.slice(0, 8) + '…')
+      : chalk.red('not found on this machine') + dim(' — run: envgit keygen --set <key>');
+  } else {
+    // Legacy
+    const legacyPath = join(projectRoot, '.envgit.key');
+    keySource = existsSync(legacyPath) ? dim('.envgit.key (legacy)') : chalk.red('(not found)');
+  }
 
   const dotenvExists = existsSync(join(projectRoot, '.env'));
 

package/src/keystore.js

@@ -1,16 +1,25 @@
-import { readFileSync, writeFileSync, chmodSync, existsSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, chmodSync, existsSync, statSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { loadConfig } from './config.js';
 
-const KEY_FILE = '.envgit.key';
 const ENV_VAR = 'ENVGIT_KEY';
 const SECURE_MODE = 0o600;
 
+function globalKeysDir() {
+  return join(homedir(), '.config', 'envgit', 'keys');
+}
+
+export function globalKeyPath(keyId) {
+  return join(globalKeysDir(), `${keyId}.key`);
+}
+
 export function findProjectRoot(startDir = process.cwd()) {
   let dir = startDir;
   while (true) {
     if (existsSync(join(dir, '.envgit'))) return dir;
     const parent = dirname(dir);
-    if (parent === dir) return null; // reached filesystem root
+    if (parent === dir) return null;
     dir = parent;
   }
 }
@@ -26,27 +35,53 @@ export function requireProjectRoot() {
 
 export function loadKey(projectRoot) {
   if (process.env[ENV_VAR]) return process.env[ENV_VAR];
-  const keyPath = join(projectRoot, KEY_FILE);
-  if (existsSync(keyPath)) {
-    const stat = statSync(keyPath);
-    const mode = stat.mode & 0o777;
-    if (mode & 0o077) {
-      console.error(
-        `Error: ${KEY_FILE} has insecure permissions (${mode.toString(8)}). Run: chmod 600 ${KEY_FILE}`
-      );
-      process.exit(1);
+
+  const config = loadConfig(projectRoot);
+
+  if (config.key_id) {
+    const keyPath = globalKeyPath(config.key_id);
+    if (existsSync(keyPath)) {
+      enforcePermissions(keyPath);
+      return readFileSync(keyPath, 'utf8').trim();
     }
-    return readFileSync(keyPath, 'utf8').trim();
+    // Project found, but this machine doesn't have the key yet
+    console.error(
+      `No key found for this project. Ask your team for the key, then run:\n  envgit keygen --set <key>`
+    );
+    process.exit(1);
   }
-  throw new Error(
-    `No encryption key found. Add it to ${KEY_FILE} or set the ENVGIT_KEY environment variable.`
+
+  // Legacy fallback: .envgit.key in project root
+  const legacyPath = join(projectRoot, '.envgit.key');
+  if (existsSync(legacyPath)) {
+    enforcePermissions(legacyPath);
+    return readFileSync(legacyPath, 'utf8').trim();
+  }
+
+  console.error(
+    `No key found for this project. Ask your team for the key, then run:\n  envgit keygen --set <key>`
   );
+  process.exit(1);
 }
 
-export function saveKey(projectRoot, key) {
-  const keyPath = join(projectRoot, KEY_FILE);
+export function saveKey(projectRoot, key, keyId) {
+  const dir = globalKeysDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const id = keyId ?? loadConfig(projectRoot).key_id;
+  const keyPath = globalKeyPath(id);
   writeFileSync(keyPath, key + '\n', { mode: SECURE_MODE });
-  // Explicitly tighten permissions in case the file already existed —
-  // writeFileSync's mode option only applies when creating a new file.
   chmodSync(keyPath, SECURE_MODE);
+  return keyPath;
+}
+
+function enforcePermissions(keyPath) {
+  const stat = statSync(keyPath);
+  const mode = stat.mode & 0o777;
+  if (mode & 0o077) {
+    console.error(
+      `Error: key file has insecure permissions (${mode.toString(8)}). Run: chmod 600 ${keyPath}`
+    );
+    process.exit(1);
+  }
 }

package/src/commands/switch.js

@@ -1,26 +0,0 @@
-import { join } from 'path';
-import { existsSync } from 'fs';
-import { requireProjectRoot, loadKey } from '../keystore.js';
-import { getEncPath } from '../config.js';
-import { readEncEnv } from '../enc.js';
-import { writeEnvFile } from '../envfile.js';
-
-export async function switchEnv(envName) {
-  const projectRoot = requireProjectRoot();
-  const key = loadKey(projectRoot);
-
-  const encPath = getEncPath(projectRoot, envName);
-  if (!existsSync(encPath)) {
-    console.error(
-      `Error: Environment '${envName}' does not exist. Use 'envgit add-env ${envName}' to create it.`
-    );
-    process.exit(1);
-  }
-
-  const vars = readEncEnv(projectRoot, envName, key);
-  const dotenvPath = join(projectRoot, '.env');
-  writeEnvFile(dotenvPath, vars);
-
-  const count = Object.keys(vars).length;
-  console.log(`Switched to [${envName}] — wrote ${count} variable${count !== 1 ? 's' : ''} to .env`);
-}