dotcrypt 0.0.0-stage → 1.1.0

package/src/server.js

@@ -0,0 +1,321 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { CONFIG_FILENAME, DEFAULT_ENVIRONMENTS, findProjectRoot, loadConfig } from './config.js';
+import { ConfirmationRequiredError, VaultError, isWithin } from './utils.js';
+import * as vault from './vault.js';
+
+export const UI_DIST_DIR = fileURLToPath(new URL('../ui/dist/', import.meta.url));
+const MAX_BODY_BYTES = 64 * 1024;
+
+export function isUiBuilt() {
+  return fs.existsSync(path.join(UI_DIST_DIR, 'index.html'));
+}
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.woff': 'font/woff',
+};
+
+const SECURITY_HEADERS = {
+  'Content-Security-Policy': [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data:",
+    "font-src 'self' data:",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    "frame-ancestors 'none'",
+  ].join('; '),
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Referrer-Policy': 'no-referrer',
+  'Cross-Origin-Opener-Policy': 'same-origin',
+  'Cross-Origin-Resource-Policy': 'same-origin',
+  'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+};
+
+const ERROR_STATUS = {
+  NO_CONFIG: 404,
+  NOT_FOUND: 404,
+  DECRYPT_FAILED: 422,
+  INVALID_VAULT: 422,
+  WEAK_PASSWORD: 400,
+  INVALID_INPUT: 400,
+  CONFIRMATION_REQUIRED: 409,
+};
+
+class HttpError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...SECURITY_HEADERS, ...headers });
+  res.end(body);
+}
+
+function sendJson(res, status, payload) {
+  send(res, status, JSON.stringify(payload), {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-store',
+  });
+}
+
+function readJsonBody(req) {
+  const type = (req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+  if (type !== 'application/json') return Promise.reject(new HttpError(415, 'Content-Type must be application/json.'));
+
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(new HttpError(413, 'Request body too large.'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks);
+      try {
+        const parsed = raw.length ? JSON.parse(raw.toString('utf8')) : {};
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+          throw new Error('not an object');
+        }
+        resolve(parsed);
+      } catch {
+        reject(new HttpError(400, 'Request body must be a JSON object.'));
+      } finally {
+        raw.fill(0); // body may contain passwords
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function errorResponse(err) {
+  if (err instanceof ConfirmationRequiredError) {
+    return [409, { code: err.code, message: err.message, reason: err.reason, diff: err.diff, hint: err.hint }];
+  }
+  if (err instanceof VaultError) {
+    return [ERROR_STATUS[err.code] ?? 400, { code: err.code, message: err.message, hint: err.hint }];
+  }
+  if (err instanceof HttpError) return [err.status, { code: 'HTTP_ERROR', message: err.message }];
+  return [500, { code: 'INTERNAL_ERROR', message: 'Unexpected server error. See the terminal for details.' }];
+}
+
+const bool = (value) => value === true;
+const str = (value) => (typeof value === 'string' ? value : undefined);
+
+/** Opens a URL in the default browser without going through a shell. */
+export function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  const child = execFile(cmd, args, { windowsHide: true }, () => {});
+  child.on('error', () => {});
+  child.unref?.();
+}
+
+/**
+ * Starts the local dashboard server bound to 127.0.0.1.
+ *
+ * Security model:
+ *  - Loopback-only listener; Host header allow-list blocks DNS-rebinding attacks.
+ *  - Every API call needs a random per-session bearer token (constant-time compare).
+ *  - Mutations require JSON + same-origin, so other websites cannot forge requests.
+ *  - Responses never contain secret values; passwords are never logged.
+ */
+export function startUiServer({ cwd = process.cwd(), port = 0, onLog = () => {} } = {}) {
+  const projectDir = findProjectRoot(cwd) ?? path.resolve(cwd);
+  const token = crypto.randomBytes(32).toString('hex');
+  const tokenBytes = Buffer.from(token, 'utf8');
+  const allowedHosts = new Set();
+
+  const hasConfig = () => fs.existsSync(path.join(projectDir, CONFIG_FILENAME));
+  const context = () => {
+    const ctx = loadConfig(projectDir);
+    if (ctx.root !== projectDir) throw new VaultError(`No ${CONFIG_FILENAME} in ${projectDir}.`, { code: 'NO_CONFIG' });
+    return ctx;
+  };
+
+  const isAuthorized = (req) => {
+    const match = /^Bearer ([a-f0-9]{64})$/.exec(req.headers.authorization ?? '');
+    return Boolean(match) && crypto.timingSafeEqual(Buffer.from(match[1], 'utf8'), tokenBytes);
+  };
+
+  const isSameOrigin = (req) => {
+    const origin = req.headers.origin;
+    if (origin !== undefined && origin !== `http://${req.headers.host}`) return false;
+    const site = req.headers['sec-fetch-site'];
+    return site === undefined || site === 'same-origin' || site === 'none';
+  };
+
+  const envActions = {
+    encrypt: (ctx, name, body) =>
+      vault.encryptEnvironment(ctx, name, str(body.password), {
+        overwrite: bool(body.overwrite),
+        replaceExisting: bool(body.replaceExisting),
+      }),
+    decrypt: (ctx, name, body) => vault.decryptEnvironment(ctx, name, str(body.password), { overwrite: bool(body.overwrite) }),
+    diff: (ctx, name, body) => vault.diffEnvironment(ctx, name, str(body.password)),
+    rotate: (ctx, name, body) => vault.rotateEnvironmentKey(ctx, name, str(body.oldPassword), str(body.newPassword)),
+    default: (ctx, name) => {
+      vault.setDefaultEnvironment(ctx, name);
+      return { status: 'ok', environment: name };
+    },
+  };
+
+  async function handleApi(req, res, pathname) {
+    if (!isAuthorized(req)) throw new HttpError(401, 'Invalid or missing session token. Reopen the URL printed in the terminal.');
+
+    if (req.method === 'GET' && pathname === '/api/status') {
+      if (!hasConfig()) {
+        return {
+          initialized: false,
+          root: projectDir,
+          configFile: CONFIG_FILENAME,
+          suggestedName: path.basename(projectDir),
+          defaultEnvironments: DEFAULT_ENVIRONMENTS,
+        };
+      }
+      const ctx = context();
+      return {
+        initialized: true,
+        ...vault.getVaultStatus(ctx),
+        gitignoreMissing: vault.repairGitignore(ctx, { dryRun: true }).gitignoreAdded,
+      };
+    }
+
+    if (req.method !== 'POST') throw new HttpError(405, 'Method not allowed.');
+    if (!isSameOrigin(req)) throw new HttpError(403, 'Cross-origin requests are not allowed.');
+    const body = await readJsonBody(req);
+
+    if (pathname === '/api/init') {
+      const environments = Array.isArray(body.environments) ? body.environments.filter((e) => typeof e === 'string') : undefined;
+      const result = vault.initVault(projectDir, {
+        name: str(body.name),
+        environments,
+        defaultEnvironment: str(body.defaultEnvironment),
+        overwrite: bool(body.overwrite),
+      });
+      onLog(`init: created ${CONFIG_FILENAME}`);
+      return { status: 'created', gitignoreAdded: result.gitignoreAdded, warnings: result.warnings };
+    }
+    if (pathname === '/api/environments') {
+      const result = vault.addEnvironment(context(), {
+        name: str(body.name),
+        file: str(body.file),
+        encryptedFile: str(body.encryptedFile),
+      });
+      onLog(`add environment: ${body.name}`);
+      return { status: 'created', gitignoreAdded: result.gitignoreAdded };
+    }
+    if (pathname === '/api/gitignore') {
+      const result = vault.repairGitignore(context());
+      onLog('.gitignore repaired');
+      return result;
+    }
+
+    const match = /^\/api\/environments\/([^/]+)\/([a-z]+)$/.exec(pathname);
+    if (match && Object.hasOwn(envActions, match[2])) {
+      const name = decodeURIComponent(match[1]);
+      const action = match[2];
+      const result = envActions[action](context(), name, body);
+      onLog(`${action} ${name}: ${result.status ?? 'ok'}`);
+      return result;
+    }
+    throw new HttpError(404, 'Not found.');
+  }
+
+  function serveStatic(req, res, pathname) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'Method not allowed');
+    let decoded;
+    try {
+      decoded = decodeURIComponent(pathname);
+    } catch {
+      return send(res, 400, 'Bad request');
+    }
+    let file = path.resolve(UI_DIST_DIR, `.${decoded}`);
+    if (!isWithin(UI_DIST_DIR, file)) return send(res, 404, 'Not found');
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) file = path.join(UI_DIST_DIR, 'index.html');
+    if (!fs.existsSync(file)) {
+      return send(res, 503, 'Dashboard assets are not built. Run "npm run build:ui" in the dotcrypt package.', {
+        'Content-Type': 'text/plain; charset=utf-8',
+      });
+    }
+
+    const type = MIME_TYPES[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+    const immutable = decoded.startsWith('/assets/');
+    send(res, 200, req.method === 'HEAD' ? undefined : fs.readFileSync(file), {
+      'Content-Type': type,
+      'Cache-Control': immutable ? 'public, max-age=31536000, immutable' : 'no-store',
+    });
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      if (!allowedHosts.has(req.headers.host ?? '')) return send(res, 421, 'Misdirected request');
+      const { pathname } = new URL(req.url ?? '/', `http://${req.headers.host}`);
+
+      if (pathname === '/api' || pathname.startsWith('/api/')) {
+        try {
+          sendJson(res, 200, await handleApi(req, res, pathname));
+        } catch (err) {
+          const [status, payload] = errorResponse(err);
+          if (status === 500) onLog(`error: ${err.stack ?? err.message}`);
+          sendJson(res, status, { error: payload });
+        }
+        return undefined;
+      }
+      return serveStatic(req, res, pathname);
+    } catch (err) {
+      onLog(`error: ${err.message}`);
+      if (!res.headersSent) send(res, 500, 'Internal error');
+      return undefined;
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      const actualPort = server.address().port;
+      allowedHosts.add(`127.0.0.1:${actualPort}`);
+      allowedHosts.add(`localhost:${actualPort}`);
+      resolve({
+        server,
+        port: actualPort,
+        projectDir,
+        token,
+        url: `http://127.0.0.1:${actualPort}/?token=${token}`,
+        close: () =>
+          new Promise((done) => {
+            server.close(() => done());
+            server.closeAllConnections?.();
+          }),
+      });
+    });
+  });
+}

package/src/sync.js

@@ -0,0 +1,100 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { MAX_FILE_SIZE, gitOutput } from './utils.js';
+
+/**
+ * Remembers, per machine, the fingerprints of the local env file and the vault file at the moment
+ * they were last known to match (after encrypt, decrypt, or an identical diff). Comparing the
+ * current files against that baseline tells us who changed what, without needing the password:
+ *
+ *   local changed only  -> you have changes to share
+ *   vault changed only  -> a teammate shared changes (after git pull)
+ *   both changed        -> conflict
+ *
+ * The state lives inside the Git directory (.git/dotcrypt/sync-state.json), so it is never
+ * committed and every clone or worktree tracks its own files.
+ */
+
+const STATE_VERSION = 1;
+
+export function fingerprint(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/** SHA-256 of a file, or null when it is missing, too large or unreadable. */
+export function fingerprintFile(absPath) {
+  try {
+    if (fs.statSync(absPath).size > MAX_FILE_SIZE) return null;
+    const data = fs.readFileSync(absPath);
+    try {
+      return fingerprint(data);
+    } finally {
+      data.fill(0);
+    }
+  } catch {
+    return null;
+  }
+}
+
+function locateState(root) {
+  const out = gitOutput(root, ['rev-parse', '--absolute-git-dir', '--show-prefix']);
+  if (!out) return null;
+  const [gitDir, prefix = ''] = out.split('\n');
+  if (!gitDir) return null;
+  return { file: path.join(gitDir, 'dotcrypt', 'sync-state.json'), project: prefix.replace(/\/$/, '') || '.' };
+}
+
+function readState(file) {
+  try {
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (state?.version === STATE_VERSION && state.projects && typeof state.projects === 'object') return state;
+  } catch {
+    // Missing or corrupt state simply means "unknown"; it is rebuilt on the next sync.
+  }
+  return { version: STATE_VERSION, projects: {} };
+}
+
+/** Opens the sync state for a project root. All methods are no-ops outside a Git repository. */
+export function openSyncState(root) {
+  const location = locateState(root);
+  const state = location ? readState(location.file) : null;
+  const entries = () => (state ? (state.projects[location.project] ?? {}) : {});
+
+  return {
+    get(envName) {
+      const entry = Object.hasOwn(entries(), envName) ? entries()[envName] : null;
+      return entry && typeof entry.local === 'string' && typeof entry.vault === 'string' ? entry : null;
+    },
+    set(envName, { local, vault }) {
+      if (!state || !local || !vault) return;
+      state.projects[location.project] = { ...entries(), [envName]: { local, vault, syncedAt: new Date().toISOString() } };
+      try {
+        fs.mkdirSync(path.dirname(location.file), { recursive: true });
+        const tmp = `${location.file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, location.file);
+      } catch {
+        // Best effort: sync tracking must never make encrypt or decrypt fail.
+      }
+    },
+  };
+}
+
+/**
+ * Plain-language sync state of one environment:
+ * empty | not-shared | not-downloaded | unknown | synced | local-changes | incoming-changes | conflict
+ */
+export function computeSync({ localExists, vaultExists, localHash, vaultHash, baseline }) {
+  if (!localExists && !vaultExists) return 'empty';
+  if (!vaultExists) return 'not-shared';
+  if (!localExists) return 'not-downloaded';
+  if (!baseline || !localHash || !vaultHash) return 'unknown';
+  const localChanged = localHash !== baseline.local;
+  const vaultChanged = vaultHash !== baseline.vault;
+  if (localChanged && vaultChanged) return 'conflict';
+  if (localChanged) return 'local-changes';
+  if (vaultChanged) return 'incoming-changes';
+  return 'synced';
+}

package/src/utils.js

@@ -0,0 +1,283 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import dotenv from 'dotenv';
+
+export const MAX_FILE_SIZE = 5 * 1024 * 1024;
+export const GITIGNORE_HEADER = '# dotcrypt: never commit plaintext environment files';
+export const BASE_GITIGNORE_RULES = Object.freeze(['.env', '.env.*', '!.env.*.enc']);
+
+export class VaultError extends Error {
+  constructor(message, { exitCode = 1, hint, code = 'VAULT_ERROR' } = {}) {
+    super(message);
+    this.name = 'VaultError';
+    this.exitCode = exitCode;
+    this.hint = hint;
+    this.code = code;
+  }
+}
+
+/**
+ * Raised when an operation would discard data and needs explicit approval.
+ * `reason` is one of: "overwrite", "password-mismatch", "unreadable-vault", "config-exists".
+ */
+export class ConfirmationRequiredError extends VaultError {
+  constructor(message, { reason, diff, hint } = {}) {
+    super(message, { code: 'CONFIRMATION_REQUIRED', hint });
+    this.name = 'ConfirmationRequiredError';
+    this.reason = reason;
+    this.diff = diff;
+  }
+}
+
+export function isWithin(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+
+/**
+ * Resolves a config-supplied relative path, rejecting absolute paths and traversal.
+ */
+export function resolveInside(root, relativePath) {
+  if (typeof relativePath !== 'string' || relativePath.trim() === '' || relativePath.includes('\0')) {
+    throw new VaultError(`Invalid path: ${JSON.stringify(relativePath)}`);
+  }
+  if (path.isAbsolute(relativePath) || path.win32.isAbsolute(relativePath)) {
+    throw new VaultError(`Path must be relative to the project root: ${relativePath}`);
+  }
+  const base = path.resolve(root);
+  const resolved = path.resolve(base, relativePath);
+  if (resolved === base || !isWithin(base, resolved)) {
+    throw new VaultError(`Path escapes the project directory: ${relativePath}`);
+  }
+  return resolved;
+}
+
+export function displayPath(root, target) {
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+export function fileExists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+/**
+ * Guards a path we are about to read or write: it must live inside the project,
+ * must not be a symlink, and no symlinked parent directory may lead outside the
+ * project. Prevents a malicious repo from redirecting writes (e.g. to ~/.bashrc)
+ * or reads (e.g. of ~/.ssh/id_rsa into a committed vault file).
+ */
+export function assertSafePath(root, target) {
+  const base = path.resolve(root);
+  const resolved = path.resolve(target);
+  const shown = displayPath(base, resolved);
+  if (resolved === base || !isWithin(base, resolved)) {
+    throw new VaultError(`Refusing to access ${resolved}: it is outside the project directory.`);
+  }
+
+  let stat = null;
+  try {
+    stat = fs.lstatSync(resolved);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  if (stat?.isSymbolicLink()) throw new VaultError(`Refusing to use ${shown}: it is a symbolic link.`);
+  if (stat && !stat.isFile()) throw new VaultError(`Refusing to use ${shown}: it is not a regular file.`);
+
+  let dir = path.dirname(resolved);
+  while (!fs.existsSync(dir)) dir = path.dirname(dir);
+  if (!isWithin(fs.realpathSync.native(base), fs.realpathSync.native(dir))) {
+    throw new VaultError(`Refusing to use ${shown}: its directory resolves outside the project.`);
+  }
+  return resolved;
+}
+
+export function safeReadFile(root, target, { maxSize = MAX_FILE_SIZE } = {}) {
+  const resolved = assertSafePath(root, target);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (err) {
+    if (err.code === 'ENOENT') throw new VaultError(`File not found: ${displayPath(root, resolved)}`);
+    throw err;
+  }
+  if (stat.size > maxSize) {
+    throw new VaultError(`${displayPath(root, resolved)} is larger than the ${maxSize} byte limit.`);
+  }
+  return fs.readFileSync(resolved);
+}
+
+/**
+ * Atomic write: data goes to an exclusive temp file in the same directory, is
+ * fsync'd, then renamed over the target. A crash never leaves a half-written file.
+ */
+export function safeWriteFile(root, target, data, { mode = 0o600 } = {}) {
+  const resolved = assertSafePath(root, target);
+  const dir = path.dirname(resolved);
+  fs.mkdirSync(dir, { recursive: true });
+  assertSafePath(root, resolved);
+
+  // Temp name starts with the target's basename so it matches the same ignore rules.
+  const tmp = path.join(dir, `${path.basename(resolved)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'wx', mode);
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(tmp, resolved);
+    try {
+      fs.chmodSync(resolved, mode);
+    } catch {
+      // chmod is best-effort (no-op on some Windows filesystems).
+    }
+  } catch (err) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+export function buffersEqual(a, b) {
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+function toPosix(p) {
+  return p.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/** True when BASE_GITIGNORE_RULES already ignore this plaintext path. */
+export function isCoveredByBaseRules(relPath) {
+  const name = path.posix.basename(toPosix(relPath));
+  return name === '.env' || (name.startsWith('.env.') && !name.endsWith('.enc'));
+}
+
+/**
+ * Appends any missing ignore rules for plaintext env files to .gitignore.
+ * Never removes or rewrites existing user rules.
+ * @returns {string[]} rules that were added.
+ */
+export function ensureGitignore(root, plaintextFiles = [], { dryRun = false } = {}) {
+  const gitignorePath = path.join(root, '.gitignore');
+  const content = fileExists(gitignorePath) ? safeReadFile(root, gitignorePath).toString('utf8') : '';
+  const existing = new Set(content.split(/\r?\n/).map((line) => line.trim()));
+
+  const wanted = [
+    ...BASE_GITIGNORE_RULES,
+    ...plaintextFiles
+      .map(toPosix)
+      .filter((file) => !isCoveredByBaseRules(file))
+      .map((file) => `/${file}`),
+  ];
+  const missing = [...new Set(wanted)].filter((rule) => !existing.has(rule));
+  if (missing.length === 0 || dryRun) return missing;
+
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  let block = '';
+  if (content.length > 0) block += content.endsWith('\n') ? eol : eol + eol;
+  if (!existing.has(GITIGNORE_HEADER)) block += GITIGNORE_HEADER + eol;
+  block += missing.join(eol) + eol;
+
+  safeWriteFile(root, gitignorePath, content + block, { mode: 0o644 });
+  return missing;
+}
+
+function runGit(root, args) {
+  try {
+    execFileSync('git', args, { cwd: root, stdio: 'ignore', windowsHide: true });
+    return 0;
+  } catch (err) {
+    return typeof err.status === 'number' ? err.status : null;
+  }
+}
+
+/**
+ * Reports whether a path is tracked or ignored by Git. `inRepo` is false when
+ * Git is unavailable or root is not inside a work tree.
+ */
+export function gitStatusOf(root, relPath) {
+  if (runGit(root, ['rev-parse', '--is-inside-work-tree']) !== 0) return { inRepo: false };
+  const file = toPosix(relPath);
+  return {
+    inRepo: true,
+    tracked: runGit(root, ['ls-files', '--error-unmatch', '--', file]) === 0,
+    ignored: runGit(root, ['check-ignore', '-q', '--', file]) === 0,
+  };
+}
+
+/** Returns trimmed stdout of a Git command, or null when it fails or Git is unavailable. */
+export function gitOutput(root, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    }).trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Describes how far a committed file is from the team:
+ *  - uncommitted: changed or new in the working tree
+ *  - unpushed: committed locally but not on the upstream branch yet
+ *  - behind: the upstream branch has a newer version (visible after a fetch)
+ * Each flag is false when unknown (no repo, no upstream).
+ */
+export function gitShareStatus(root, relPath) {
+  const file = toPosix(relPath);
+  const uncommitted = Boolean(gitOutput(root, ['status', '--porcelain', '--untracked-files=all', '--', file]));
+  const hasUpstream = gitOutput(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']) !== null;
+  if (!hasUpstream) return { uncommitted, unpushed: false, behind: false, hasUpstream };
+  const touched = (range) => Boolean(gitOutput(root, ['log', '-1', '--format=%H', range, '--', file]));
+  return { uncommitted, unpushed: touched('@{u}..HEAD'), behind: touched('HEAD..@{u}'), hasUpstream };
+}
+
+export function parseEnv(content) {
+  return dotenv.parse(content);
+}
+
+/**
+ * Compares variable maps by key. Returns key names only, never values.
+ * "added" = only in local, "removed" = only in vault, "changed" = value differs.
+ */
+export function diffEnv(vaultVars, localVars) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  let unchanged = 0;
+  for (const key of Object.keys(localVars)) {
+    if (!Object.hasOwn(vaultVars, key)) added.push(key);
+    else if (vaultVars[key] !== localVars[key]) changed.push(key);
+    else unchanged += 1;
+  }
+  for (const key of Object.keys(vaultVars)) {
+    if (!Object.hasOwn(localVars, key)) removed.push(key);
+  }
+  return { added: added.sort(), removed: removed.sort(), changed: changed.sort(), unchanged };
+}
+
+export function hasDifferences({ added, removed, changed }) {
+  return added.length + removed.length + changed.length > 0;
+}
+
+/** Strips control characters so decrypted key names cannot inject terminal escapes. */
+export function sanitizeForTerminal(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+}