@akshxy/envgit 0.4.3 → 0.5.1

package/README.md

@@ -14,7 +14,7 @@ npm install -g @akshxy/envgit
 
 - Secrets are encrypted with **AES-256-GCM** and live in `.envgit/` — safe to commit
 - The key lives on **your machine only** (`~/.config/envgit/keys/`) — never touches the repo
-- Teammates just run `envgit keygen --set <key>` after cloning — no manual file management
+- Onboard a teammate in one command: `envgit share` → send them the link → they run `envgit join`
 - `envgit unpack dev` writes a clean, **beautifully formatted `.env`** grouped by service
 
 ---
@@ -49,18 +49,23 @@ envgit init
 envgit set DB_URL=postgres://... OPENAI_API_KEY=sk-...
 git add .envgit/ && git commit -m "chore: encrypted env"
 
-envgit keygen --show
-# Prints your key — send it to teammates via 1Password, Bitwarden, etc.
+envgit share
+# ✓ Key encrypted and uploaded. Link expires in 24 hours, usable once.
+#
+#   envgit join abc123... --code Xk9mP2...==
+#
+# Send that one line to your teammate — nothing else needed.
 
 # ── Developer B (teammate, after cloning) ─────────────────
-envgit keygen --set <key-from-teammate>
-# Key is saved to ~/.config/envgit/keys/<project-id>.key automatically
-# No file paths to think about — it just works
+envgit join abc123... --code Xk9mP2...==
+# ✓ Key saved to ~/.config/envgit/keys/<project-id>.key
 
 envgit verify        # confirm the key works
 envgit unpack dev    # writes .env
 ```
 
+The relay is **cryptographically blind** — it stores only AES-256-GCM ciphertext and never sees the passphrase. The link is deleted the moment your teammate uses it.
+
 ---
 
 ## Formatted `.env` output
@@ -127,8 +132,10 @@ Supports 100+ services out of the box: OpenAI, Anthropic, Groq, Stripe, Supabase
 |---------|-------------|
 | `envgit init` | Initialize project, generate key, save to `~/.config/envgit/keys/` |
 | `envgit keygen` | Generate a new key for the current project |
-| `envgit keygen --show` | Print current key to share with teammates |
-| `envgit keygen --set <key>` | Save a teammate's key for the current project |
+| `envgit keygen --show` | Print current key |
+| `envgit keygen --set <key>` | Save a key for the current project |
+| `envgit share` | Upload encrypted key to a one-time relay link |
+| `envgit join <token> --code <passphrase>` | Download and save a key shared via `envgit share` |
 | `envgit rotate-key` | Generate new key and re-encrypt all environments |
 | `envgit verify` | Confirm all environments decrypt with the current key |
 
@@ -167,6 +174,15 @@ Supports 100+ services out of the box: OpenAI, Anthropic, Groq, Stripe, Supabase
 | `envgit run -- node server.js` | Run a command with env vars injected, nothing written to disk |
 | `envgit import --file .env.local` | Encrypt an existing `.env` file |
 
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `envgit doctor` | Check everything — key, envs, git safety — in one shot |
+| `envgit audit` | Show which keys are missing across environments |
+| `envgit template` | Generate a `.env.example` with all keys, no values |
+| `envgit template --output .env.example --force` | Overwrite existing file |
+
 ### Status
 
 | Command | Description |
@@ -216,3 +232,6 @@ ENVGIT_KEY=$(cat ~/.config/envgit/keys/<id>.key) envgit run -- node server.js
 - **File permissions enforced** — key files are locked to `0600`, errors if too permissive
 - **Key bytes zeroized** from memory immediately after use
 - **No plaintext ever written** except when you explicitly run `envgit unpack`
+- **Relay is blind** — `envgit share` encrypts your key with a one-time passphrase before upload. The relay stores only ciphertext and never sees the passphrase. Even a full relay compromise leaks nothing.
+- **One-time links** — tokens are deleted on first use via a strongly consistent Durable Object. Replay attacks are impossible.
+- **24-hour TTL** — unclaimed tokens are automatically destroyed

package/bin/envgit.js

@@ -18,6 +18,11 @@ import { envs } from '../src/commands/envs.js';
 import { exportEnv } from '../src/commands/export.js';
 import { verify } from '../src/commands/verify.js';
 import { rotateKey } from '../src/commands/rotate-key.js';
+import { share } from '../src/commands/share.js';
+import { join } from '../src/commands/join.js';
+import { doctor } from '../src/commands/doctor.js';
+import { audit } from '../src/commands/audit.js';
+import { template } from '../src/commands/template.js';
 
 program
   .name('envgit')
@@ -137,4 +142,32 @@ program
   .description('Generate a new key and re-encrypt all environments')
   .action(rotateKey);
 
+program
+  .command('doctor')
+  .description('Check project health — key, envs, git safety')
+  .action(doctor);
+
+program
+  .command('audit')
+  .description('Show which keys are missing across environments')
+  .action(audit);
+
+program
+  .command('template')
+  .description('Generate a .env.example with all keys but no values')
+  .option('-o, --output <path>', 'output file path', '.env.example')
+  .option('-f, --force', 'overwrite if file already exists')
+  .action(template);
+
+program
+  .command('share')
+  .description('Encrypt your key and upload it to a one-time link — send the output to a teammate')
+  .action(share);
+
+program
+  .command('join <token>')
+  .description('Download and save a key from a link generated by envgit share')
+  .requiredOption('--code <passphrase>', 'passphrase printed by envgit share')
+  .action(join);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshxy/envgit",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Encrypted per-project environment variable manager",
   "type": "module",
   "bin": {

package/src/commands/audit.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { requireProjectRoot, loadKey } from '../keystore.js';
+import { loadConfig } from '../config.js';
+import { readEncEnv } from '../enc.js';
+import { bold, dim, ok } from '../ui.js';
+
+export async function audit() {
+  const projectRoot = requireProjectRoot();
+  const key         = loadKey(projectRoot);
+  const config      = loadConfig(projectRoot);
+
+  if (config.envs.length < 2) {
+    console.log(dim('\n  Need at least 2 environments to audit.\n'));
+    return;
+  }
+
+  // Load all envs
+  const envVars = {};
+  for (const envName of config.envs) {
+    envVars[envName] = readEncEnv(projectRoot, envName, key);
+  }
+
+  // Collect every key across all envs
+  const allKeys = [...new Set(config.envs.flatMap(e => Object.keys(envVars[e])))].sort();
+
+  if (allKeys.length === 0) {
+    console.log(dim('\n  No variables found across any environment.\n'));
+    return;
+  }
+
+  // Find keys that are missing from at least one env
+  const missing = {};   // key → [envs it's missing from]
+  const present = {};   // key → [envs it's in]
+
+  for (const key of allKeys) {
+    missing[key] = config.envs.filter(e => !(key in envVars[e]));
+    present[key] = config.envs.filter(e =>  (key in envVars[e]));
+  }
+
+  const problemKeys = allKeys.filter(k => missing[k].length > 0);
+  const cleanKeys   = allKeys.filter(k => missing[k].length === 0);
+
+  // ── Header ────────────────────────────────────────────────────────────────
+  console.log('');
+  console.log(bold('Audit') + dim(` — ${config.envs.join(', ')}`));
+  console.log('');
+
+  // ── Missing keys ──────────────────────────────────────────────────────────
+  if (problemKeys.length === 0) {
+    ok(`All ${allKeys.length} keys are present in every environment.`);
+    console.log('');
+    return;
+  }
+
+  // Column header
+  const pad = Math.max(...allKeys.map(k => k.length), 4) + 2;
+  const envHeaders = config.envs.map(e => e.padEnd(8)).join('  ');
+  console.log(dim('  ' + 'KEY'.padEnd(pad) + envHeaders));
+  console.log(dim('  ' + '─'.repeat(pad + config.envs.length * 10)));
+
+  for (const key of problemKeys) {
+    const cols = config.envs.map(e => {
+      if (key in envVars[e]) return chalk.green('  ✓'.padEnd(10));
+      return chalk.red('  ✗'.padEnd(10));
+    }).join('');
+    console.log(`  ${chalk.bold(key.padEnd(pad))}${cols}`);
+  }
+
+  if (cleanKeys.length > 0) {
+    console.log(dim(`\n  ${cleanKeys.length} key${cleanKeys.length !== 1 ? 's' : ''} present in all envs (hidden)`));
+  }
+
+  console.log('');
+  console.log(chalk.yellow(bold(`${problemKeys.length} key${problemKeys.length !== 1 ? 's' : ''} missing from one or more environments.`)));
+
+  // Per-env fix hints
+  console.log('');
+  for (const envName of config.envs) {
+    const needed = problemKeys.filter(k => !(k in envVars[envName]));
+    if (needed.length > 0) {
+      console.log(dim(`  Fix ${envName}:  envgit set ${needed.join('=... ')}=... --env ${envName}`));
+    }
+  }
+
+  console.log('');
+}

package/src/commands/doctor.js

@@ -0,0 +1,146 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { findProjectRoot, globalKeyPath } from '../keystore.js';
+import { loadConfig } from '../config.js';
+import { readEncEnv } from '../enc.js';
+import { bold, dim } from '../ui.js';
+
+function pass(msg)      { console.log(chalk.green(`  ✓ ${msg}`)); }
+function fail(msg)      { console.log(chalk.red(`  ✗ ${msg}`)); }
+function warn(msg)      { console.log(chalk.yellow(`  ⚠ ${msg}`)); }
+function section(title) { console.log(`\n${bold(title)}`); }
+
+export async function doctor() {
+  let issues = 0;
+
+  // ── Project ───────────────────────────────────────────────────────────────
+  section('Project');
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    fail('No envgit project found — run envgit init first.');
+    console.log('');
+    process.exit(1);
+  }
+  pass(`Project root: ${dim(projectRoot)}`);
+
+  let config;
+  try {
+    config = loadConfig(projectRoot);
+    pass(`Config loaded ${dim(`(${config.envs.length} env${config.envs.length !== 1 ? 's' : ''}: ${config.envs.join(', ')})`)}`)
+  } catch (e) {
+    fail(`Config unreadable — ${e.message}`);
+    issues++;
+  }
+
+  // ── Key ───────────────────────────────────────────────────────────────────
+  section('Key');
+
+  let key = null;
+  if (process.env.ENVGIT_KEY) {
+    pass('Key loaded from ENVGIT_KEY environment variable');
+    key = process.env.ENVGIT_KEY;
+  } else if (config?.key_id) {
+    const keyPath = globalKeyPath(config.key_id);
+    if (existsSync(keyPath)) {
+      pass(`Key file found ${dim(keyPath)}`);
+      key = readFileSync(keyPath, 'utf8').trim();
+    } else {
+      fail('Key file missing — run: envgit share / envgit join');
+      issues++;
+    }
+  } else {
+    const legacyPath = join(projectRoot, '.envgit.key');
+    if (existsSync(legacyPath)) {
+      warn(`Legacy key file at project root ${dim('(consider migrating)')}`);
+      key = readFileSync(legacyPath, 'utf8').trim();
+    } else {
+      fail('No key found — run: envgit keygen');
+      issues++;
+    }
+  }
+
+  if (key) {
+    const decoded = Buffer.from(key, 'base64');
+    if (decoded.length === 32) {
+      pass('Key length valid (256-bit)');
+    } else {
+      fail(`Key length invalid — got ${decoded.length} bytes, expected 32`);
+      issues++;
+    }
+  }
+
+  // ── Environments ──────────────────────────────────────────────────────────
+  if (config && key) {
+    section('Environments');
+    for (const envName of config.envs) {
+      try {
+        const vars = readEncEnv(projectRoot, envName, key);
+        const count = Object.keys(vars).length;
+        pass(`${envName} decrypts OK ${dim(`(${count} var${count !== 1 ? 's' : ''})`)}`);
+      } catch (e) {
+        fail(`${envName} failed to decrypt — ${e.message}`);
+        issues++;
+      }
+    }
+  }
+
+  // ── Git safety ────────────────────────────────────────────────────────────
+  section('Git safety');
+
+  const gitignorePath = join(projectRoot, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    const gitignore = readFileSync(gitignorePath, 'utf8');
+    const lines = gitignore.split('\n').map(l => l.trim());
+
+    const envIgnored = lines.some(l => l === '.env' || l === '.env.*' || l === '*.env');
+    if (envIgnored) {
+      pass('.env is in .gitignore');
+    } else {
+      warn('.env is not in .gitignore — add it to prevent accidental commits');
+      issues++;
+    }
+
+    if (existsSync(join(projectRoot, '.envgit.key'))) {
+      const keyIgnored = lines.some(l => l === '.envgit.key');
+      if (!keyIgnored) {
+        fail('.envgit.key is not in .gitignore — this would expose your key!');
+        issues++;
+      }
+    }
+  } else {
+    warn('No .gitignore found');
+    issues++;
+  }
+
+  // Check for .env files tracked by git (no shell, no injection)
+  try {
+    const tracked = execFileSync('git', ['ls-files', '.env', '.env.local', '.env.production'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).toString().trim();
+
+    if (tracked) {
+      const files = tracked.split('\n').map(f => `    ${f}`).join('\n');
+      fail(`Plaintext .env file tracked by git:\n${files}`);
+      fail('Remove with: git rm --cached .env');
+      issues++;
+    } else {
+      pass('No plaintext .env files tracked by git');
+    }
+  } catch {
+    warn('Not a git repo — skipping git tracking check');
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  console.log('');
+  if (issues === 0) {
+    console.log(chalk.green(bold('All checks passed.')));
+  } else {
+    console.log(chalk.red(bold(`${issues} issue${issues !== 1 ? 's' : ''} found.`)));
+    process.exit(1);
+  }
+  console.log('');
+}

package/src/commands/join.js

@@ -0,0 +1,50 @@
+import { findProjectRoot, saveKey } from '../keystore.js';
+import { decrypt } from '../crypto.js';
+import { ok, fatal, bold, dim } from '../ui.js';
+
+const RELAY = process.env.ENVGIT_RELAY ?? 'https://envgit-relay.akku41809.workers.dev';
+
+export async function join(token, options) {
+  if (!token)         fatal('Token required. Usage: envgit join <token> --code <passphrase>');
+  if (!options.code)  fatal('Passphrase required. Usage: envgit join <token> --code <passphrase>');
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) fatal('No envgit project found. Clone the repo and run envgit init first, or just be inside the project directory.');
+
+  let blob;
+  try {
+    const res = await fetch(`${RELAY}/join/${token}`);
+
+    if (res.status === 404) fatal('Token not found or already used. Ask your teammate to run envgit share again.');
+    if (res.status === 410) fatal('Token has expired. Ask your teammate to run envgit share again.');
+    if (!res.ok)            fatal(`Relay error: ${res.status}`);
+
+    ({ blob } = await res.json());
+  } catch (e) {
+    if (e.cause?.code === 'ENOTFOUND') fatal('Cannot reach relay — check your connection.');
+    fatal(`Join failed: ${e.message}`);
+  }
+
+  let key;
+  try {
+    key = decrypt(blob, options.code);
+  } catch {
+    fatal('Decryption failed — wrong --code, or the blob was tampered with.');
+  }
+
+  // Validate it looks like a real key before saving
+  const decoded = Buffer.from(key, 'base64');
+  if (decoded.length !== 32) {
+    fatal('Decrypted value is not a valid envgit key. Wrong --code?');
+  }
+
+  const keyPath = saveKey(projectRoot, key);
+
+  console.log('');
+  ok('Key saved.');
+  console.log(dim(`  Stored at: ${keyPath}`));
+  console.log('');
+  console.log(dim('Run `envgit verify` to confirm it works.'));
+  console.log(dim('Run `envgit unpack dev` to write your .env file.'));
+  console.log('');
+}

package/src/commands/share.js

@@ -0,0 +1,48 @@
+import { randomBytes } from 'crypto';
+import { findProjectRoot, loadKey } from '../keystore.js';
+import { encrypt, generateKey } from '../crypto.js';
+import { ok, fatal, bold, dim } from '../ui.js';
+
+const RELAY = process.env.ENVGIT_RELAY ?? 'https://envgit-relay.akku41809.workers.dev';
+
+export async function share() {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) fatal('No envgit project found. Run envgit init first.');
+
+  let key;
+  try { key = loadKey(projectRoot); }
+  catch (e) { fatal(e.message); }
+
+  // Generate a one-time passphrase — used to encrypt the key before it leaves
+  // the machine. The relay stores only ciphertext; it never sees this passphrase.
+  const passphrase = generateKey(); // 32 bytes of OS randomness, base64-encoded
+  const blob       = encrypt(key, passphrase);
+
+  let token;
+  try {
+    const res = await fetch(`${RELAY}/share`, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify({ blob }),
+    });
+
+    if (res.status === 429) fatal('Rate limit hit — try again in an hour.');
+    if (!res.ok)            fatal(`Relay error: ${res.status}`);
+
+    ({ token } = await res.json());
+  } catch (e) {
+    if (e.cause?.code === 'ENOTFOUND') fatal('Cannot reach relay — check your connection.');
+    fatal(`Share failed: ${e.message}`);
+  }
+
+  console.log('');
+  ok('Key encrypted and uploaded. Link expires in 24 hours, usable once.');
+  console.log('');
+  console.log(bold('Send this to your teammate:'));
+  console.log('');
+  console.log(`  envgit join ${token} --code ${passphrase}`);
+  console.log('');
+  console.log(dim('They can run it directly in their terminal after cloning.'));
+  console.log(dim('The link is deleted the moment they use it.'));
+  console.log('');
+}

package/src/commands/template.js

@@ -0,0 +1,53 @@
+import { writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { requireProjectRoot, loadKey } from '../keystore.js';
+import { loadConfig } from '../config.js';
+import { readEncEnv } from '../enc.js';
+import { ok, warn, fatal, bold, dim } from '../ui.js';
+
+export async function template(options) {
+  const projectRoot = requireProjectRoot();
+  const key         = loadKey(projectRoot);
+  const config      = loadConfig(projectRoot);
+
+  // Merge keys from all envs (union), sorted
+  const allKeys = [...new Set(
+    config.envs.flatMap(envName => Object.keys(readEncEnv(projectRoot, envName, key)))
+  )].sort();
+
+  if (allKeys.length === 0) {
+    warn('No variables found — nothing to template.');
+    return;
+  }
+
+  const outPath = join(projectRoot, options.output ?? '.env.example');
+
+  if (existsSync(outPath) && !options.force) {
+    fatal(`${outPath} already exists. Use --force to overwrite.`);
+  }
+
+  const projectName = config.project ?? 'your-project';
+  const envList     = config.envs.join(', ');
+
+  const lines = [
+    `# .env.example — generated by envgit`,
+    `# Project : ${projectName}`,
+    `# Envs    : ${envList}`,
+    `#`,
+    `# Do not put real values here. This file is safe to commit.`,
+    `# To get the real values: envgit join <token> --code <passphrase>`,
+    `#                    then: envgit unpack dev`,
+    ``,
+    ...allKeys.map(k => `${k}=`),
+    ``,
+  ].join('\n');
+
+  writeFileSync(outPath, lines, 'utf8');
+
+  console.log('');
+  ok(`Generated ${dim(outPath)} with ${allKeys.length} key${allKeys.length !== 1 ? 's' : ''}`);
+  console.log(dim(`  Envs scanned: ${envList}`));
+  console.log('');
+  console.log(dim(`  Commit it:  git add ${options.output ?? '.env.example'} && git commit -m "chore: update .env.example"`));
+  console.log('');
+}