p2p-envsync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 RismanRJ
+
+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,201 @@
+# EnvSync
+
+P2P, offline-first, encrypted `.env` sync for dev teams — no central server, LAN multicast for instant sync, GitHub as encrypted backup/relay.
+
+![npm](https://img.shields.io/badge/npm-envsync-blue) ![license](https://img.shields.io/badge/license-MIT-green) ![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+
+## Install
+
+```
+npm install -g envsync
+```
+
+Prerequisites: Node.js 18+, `gh` CLI (for GitHub backup features).
+
+## Quick Start
+
+```
+# User A: create a room from an existing .env file
+envsync create myproject .env
+
+# User A shares the room name + key with User B (via `envsync invite`)
+
+# User B: join with the shared key
+envsync join myproject /path/to/.env <key>
+
+# Both: start syncing over LAN
+envsync sync myproject
+```
+
+Changes to either `.env` file now sync automatically over LAN multicast.
+
+## Vault-Only Mode
+
+No `.env` file ever touches disk — values live only in the encrypted vault.
+
+```
+envsync create myproject
+envsync set myproject DB_HOST localhost
+envsync run myproject -- npm start
+envsync export myproject
+```
+
+`run` injects values into a subprocess's environment; `export` prints `export KEY=VALUE` lines for shell/direnv eval (`--format=env` for a plain `KEY=VALUE` `.env`-style file).
+
+## CLI Reference
+
+### Room management
+
+| Command | Description |
+|---|---|
+| `envsync create <name> [file]` | Create a room; omit `file` for vault-only (no plaintext file ever) |
+| `envsync join <name> <file> <key>` | Join an existing room with a shared key |
+| `envsync init <name>` | Write `.envsync.yml` in this dir (metadata only, no secrets) |
+| `envsync status` | List all rooms and whether they have unsynced local edits |
+
+### Syncing
+
+| Command | Description |
+|---|---|
+| `envsync sync [name]` | Watch + LAN P2P sync with other peers |
+| `envsync watch [name]` | Local-only: watch + encrypted history, no networking |
+| `envsync daemon` | Headless: sync every locally known room in one process |
+| `envsync daemon install\|uninstall\|status` | Manage the macOS launchd agent for `daemon` |
+
+### Values
+
+| Command | Description |
+|---|---|
+| `envsync set [name] <key> <value>` | Set a value directly in the vault, no file needed |
+| `envsync unset [name] <key>` | Remove a value directly from the vault |
+| `envsync review [name] [--reveal]` | Show the last change, values masked by default |
+| `envsync preview [name] [--reveal]` | Show every current key, values masked by default |
+| `envsync history [name]` | Print decrypted change history |
+
+### Runtime injection
+
+| Command | Description |
+|---|---|
+| `envsync run [name] -- <cmd> [args]` | Run a command with room values injected into its env (never written to disk) |
+| `envsync export [name] [--format=env]` | Print `export KEY=VALUE` lines, or plain `KEY=VALUE` with `--format=env` |
+
+### Identity
+
+| Command | Description |
+|---|---|
+| `envsync identity` | Print this device's alias and public key |
+| `envsync alias [new-name]` | Print or set this device's display name |
+
+### Sharing
+
+| Command | Description |
+|---|---|
+| `envsync invite [name]` | Reprint the QR code / join command for an existing room |
+| `envsync invite-device <name> <pubkey>` | Wrap the room key for one device's public key, safe to paste anywhere |
+| `envsync accept <name> <file> <env>` | Unwrap a device-targeted envelope from `invite-device` and join |
+
+### GitHub backup
+
+| Command | Description |
+|---|---|
+| `envsync connect-github [repo-name]` | Sign in to GitHub once, create/reuse one shared private repo, push every room |
+| `envsync backup-init <repo-url>` | Point the shared backup at an existing private repo you already created |
+| `envsync backup [name]` | Push one room into the shared GitHub backup |
+| `envsync restore [name] [repo-url]` | Pull a room from the shared GitHub backup (needs the room key locally already) |
+| `envsync invite-github <username>` | Grant a teammate collaborator access to the shared private backup repo |
+| `envsync revoke-github <username>` | Remove a collaborator from the shared private backup repo |
+
+### Key management
+
+| Command | Description |
+|---|---|
+| `envsync rotate [name]` | Generate a new encryption key for this room and append to history |
+
+`name` is optional wherever a `.envsync.yml` exists in or above the current directory.
+
+## GitHub Backup & Relay
+
+```
+envsync connect-github myteam-envsync
+```
+
+This authenticates via the `gh` CLI and creates (or reuses) one private repo shared across all your rooms. Every sync merge auto-pushes to it, debounced 3s after the merge with automatic retry every 60s. When peers aren't on the same LAN, the same repo doubles as an async relay: each peer pulls from it every ~45s and merges through the same last-write-wins logic, so it never blind-overwrites local state.
+
+Invite a collaborator so they can push/pull the shared backup:
+
+```
+envsync invite-github <username>
+```
+
+## Peer Discovery Layers
+
+Peers are found through four layers, roughly fastest-to-slowest:
+
+1. **LAN multicast** — UDP multicast (`239.255.42.99:41234`, every 3s), instant, on by default.
+2. **Tailscale/ZeroTier mesh** — detected automatically, bypasses AP isolation on networks that block multicast.
+3. **GitHub gist signaling** — works across any network for peer handshake.
+4. **GitHub git relay** — async fallback, ~45s pull interval, for peers with no direct path to each other.
+
+## VS Code Extension
+
+Install the `.vsix` from the `vscode-extension/` directory (`code --install-extension envsync-*.vsix`).
+
+- Shield icon on a `.env` file with no `.envsync.yml` room — vault it.
+- Check icon — review pending changes (masked diff).
+- Status bar — shows sync state, room name, and last-change time for the workspace's tracked file.
+
+## Tray App (Electron)
+
+```
+npm run tray
+# or
+npx electron .
+```
+
+Menu covers: create/join rooms, sync now/stop per room, preview (masked/unmasked), review last change, and GitHub backup (connect, invite collaborator, connected-repo status). Auto-refreshes every 5s.
+
+## Auto-Start Daemon (macOS)
+
+```
+envsync daemon install
+envsync daemon status
+envsync daemon uninstall
+```
+
+Installs a launchd agent that runs `envsync daemon` on login, syncing every locally known room in one process. Logs to `~/.envsync/daemon.log`.
+
+## Project Config (`.envsync.yml`)
+
+Auto-created by `envsync init <name>` in the current directory. Maps that directory to a room name so `envsync run`, `sync`, and the VS Code extension can find the right room without passing `name` explicitly.
+
+## Security Model
+
+- AES-256-GCM encryption at rest (merged state, history log, backup payloads) and in transit (TCP sync).
+- X25519 per-device keypairs for envelope encryption — a room key can be granted to one device via `invite-device`/`accept` without a shared-secret channel.
+- Room keys are never sent in plaintext; LAN discovery advertises rooms via HMAC-SHA256(room key), and the TCP handshake is a challenge-response mutual auth over the same HMAC.
+- GitHub sees only encrypted blobs — the backup repo holds ciphertext, never plaintext values.
+- All sensitive files (`~/.envsync/identity.json`, room state, history) are `chmod 0600`.
+
+## Development
+
+```
+npm test
+npm run tray
+```
+
+Project structure:
+
+| File | Purpose |
+|---|---|
+| `cli.js` | CLI entry point and command dispatch |
+| `lib.js` | Core room/state/encryption logic |
+| `net.js` | LAN multicast discovery + TCP P2P sync |
+| `mesh.js` | Tailscale/ZeroTier mesh detection |
+| `signal.js` | GitHub gist peer signaling |
+| `backup.js` | GitHub backup/relay (push/pull/invite) |
+| `notify.js` | Cross-platform OS notifications |
+| `tray/` | Electron tray app |
+
+## License
+
+MIT

package/backup.js

@@ -0,0 +1,211 @@
+'use strict';
+
+// Backup/restore ALL rooms' encrypted vaults (merged.json + history.jsonl --
+// both already AES-256-GCM encrypted, never plaintext) to ONE shared private
+// GitHub repo, one subfolder per room. Connect once; every room's `sync`
+// pushes into its own subfolder of the same repo. Plain `git`/`gh` shelled
+// out to -- no GitHub API client library, no server of our own to run.
+// This is a backup channel, not the sync transport: LAN P2P (net.js) stays
+// the primary, always-on path; this is what recovers a room if no LAN peer
+// is ever reachable, or a device is lost.
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const lib = require('./lib');
+
+function sharedDir() {
+  return path.join(path.dirname(lib.ROOT), 'backup');
+}
+
+function backupConfigFile() {
+  return path.join(path.dirname(lib.ROOT), 'backup-config.json');
+}
+
+function loadBackupConfig() {
+  const file = backupConfigFile();
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
+}
+
+function saveBackupConfig(config) {
+  const file = backupConfigFile();
+  fs.writeFileSync(file, JSON.stringify(config, null, 2));
+  fs.chmodSync(file, 0o600);
+}
+
+function isConnected() {
+  return loadBackupConfig() !== null;
+}
+
+function git(args) {
+  return execFileSync('git', args, { cwd: sharedDir(), stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+}
+
+// One-time setup: point the shared backup repo at a GitHub URL.
+function connectRepo(repoUrl) {
+  const dir = sharedDir();
+  fs.mkdirSync(dir, { recursive: true });
+  if (!fs.existsSync(path.join(dir, '.git'))) {
+    git(['init']);
+    git(['checkout', '-b', 'main']);
+  }
+  const remotes = git(['remote']).split('\n').filter(Boolean);
+  if (remotes.includes('origin')) git(['remote', 'set-url', 'origin', repoUrl]);
+  else git(['remote', 'add', 'origin', repoUrl]);
+  saveBackupConfig({ repoUrl });
+}
+
+function stageRoom(name) {
+  const dir = path.join(sharedDir(), name);
+  fs.mkdirSync(dir, { recursive: true });
+  const roomFile = path.join(lib.roomDir(name), 'merged.json');
+  const historyFile = path.join(lib.roomDir(name), 'history.jsonl');
+  if (fs.existsSync(roomFile)) fs.copyFileSync(roomFile, path.join(dir, 'merged.json'));
+  if (fs.existsSync(historyFile)) fs.copyFileSync(historyFile, path.join(dir, 'history.jsonl'));
+}
+
+// Best-effort push: called opportunistically (after a merge, or on a timer)
+// while `sync` is running. Silently does nothing if not connected yet or
+// there's no internet -- this is what "keeps in sync with the cloud
+// whenever connected" means in practice: retry next time, don't block.
+function pushBackup(name) {
+  if (!isConnected()) return { ok: false, reason: 'not connected -- run "envsync connect-github"' };
+  stageRoom(name);
+  try {
+    git(['add', name]);
+    if (git(['status', '--porcelain']).trim()) {
+      git(['commit', '-m', `envsync backup: ${name} ${new Date().toISOString()}`]);
+    }
+    try {
+      git(['push', '-u', 'origin', 'main']);
+    } catch {
+      // another room/device pushed in between -- rebase once and retry
+      git(['pull', '--rebase', 'origin', 'main']);
+      git(['push', '-u', 'origin', 'main']);
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: (err.stderr || err.message).toString().trim().split('\n').pop() };
+  }
+}
+
+// Phase 5: read-only fetch for the async relay in net.js -- pulls the
+// shared repo and decrypts the room's remote merged state WITHOUT
+// touching local room files. The caller merges this through the same
+// last-write-wins logic used for LAN peers (applyMergedUpdate), so a
+// stale or divergent remote can never blindly clobber local state.
+function fetchRemoteMerged(name) {
+  if (!isConnected()) return { ok: false, reason: 'not connected' };
+  try {
+    git(['pull', '--rebase', 'origin', 'main']);
+  } catch (err) {
+    return { ok: false, reason: (err.stderr || err.message).toString().trim().split('\n').pop() };
+  }
+  const file = path.join(sharedDir(), name, 'merged.json');
+  if (!fs.existsSync(file)) return { ok: true, merged: {} };
+  try {
+    const config = lib.loadConfig(name);
+    const encrypted = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { ok: true, merged: lib.decrypt(config.key, encrypted) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+function pullBackup(name) {
+  if (!isConnected()) return { ok: false, reason: 'not connected -- run "envsync connect-github"' };
+  try {
+    git(['pull', '--rebase', 'origin', 'main']);
+  } catch (err) {
+    return { ok: false, reason: (err.stderr || err.message).toString().trim().split('\n').pop() };
+  }
+  const dir = path.join(sharedDir(), name);
+  const roomFile = path.join(lib.roomDir(name), 'merged.json');
+  const historyFile = path.join(lib.roomDir(name), 'history.jsonl');
+  if (fs.existsSync(path.join(dir, 'merged.json'))) fs.copyFileSync(path.join(dir, 'merged.json'), roomFile);
+  if (fs.existsSync(path.join(dir, 'history.jsonl'))) fs.copyFileSync(path.join(dir, 'history.jsonl'), historyFile);
+  return { ok: true };
+}
+
+// --- GitHub connection, via the `gh` CLI (browser OAuth is `gh`'s job,
+// not ours -- no reason to reimplement it when the CLI already does it
+// well and is likely already installed on a dev machine). ---
+
+function isGhInstalled() {
+  try { execFileSync('gh', ['--version']); return true; } catch { return false; }
+}
+
+function isGhAuthenticated() {
+  try { execFileSync('gh', ['auth', 'status']); return true; } catch { return false; }
+}
+
+function githubLogin() {
+  return execFileSync('gh', ['api', 'user', '--jq', '.login']).toString().trim();
+}
+
+// Blocks until the user finishes the browser flow -- fine for a CLI
+// (it has a controlling terminal). The tray can't block this way; see
+// tray/main.js for how it opens a real Terminal window instead.
+function loginInteractive() {
+  execFileSync('gh', ['auth', 'login', '--web', '--git-protocol', 'https'], { stdio: 'inherit' });
+}
+
+// Parses "https://github.com/<owner>/<repo>.git" -- the only shape
+// connectRepo/createGithubRepo ever produce or accept.
+function parseRepoUrl(url) {
+  const match = url.match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (!match) throw new Error(`Not a recognizable GitHub URL: ${url}`);
+  return { owner: match[1], repo: match[2] };
+}
+
+// The repo is kept private, so a new peer's own GitHub account needs
+// collaborator access before their `sync` can push/pull the shared
+// backup -- only the repo's owner/admin can grant that. GitHub sends the
+// invitee a real invite they still have to accept themselves; this just
+// starts that process via `gh api` instead of the web UI.
+function addCollaborator(username) {
+  const config = loadBackupConfig();
+  if (!config) throw new Error('not connected -- run "envsync connect-github" first');
+  const { owner, repo } = parseRepoUrl(config.repoUrl);
+  execFileSync('gh', ['api', `repos/${owner}/${repo}/collaborators/${username}`, '-X', 'PUT']);
+}
+
+function removeCollaborator(username) {
+  const config = loadBackupConfig();
+  if (!config) throw new Error('not connected -- run "envsync connect-github" first');
+  const { owner, repo } = parseRepoUrl(config.repoUrl);
+
+  try {
+    execFileSync('gh', ['api', `repos/${owner}/${repo}/collaborators/${username}`, '-X', 'DELETE']);
+  } catch {
+    // Not an accepted collaborator; check for pending invitation instead
+  }
+
+  try {
+    const invitationsJson = execFileSync('gh', ['api', `repos/${owner}/${repo}/invitations`]).toString();
+    const invitations = JSON.parse(invitationsJson);
+    const invitation = invitations.find(inv => inv.invitee.login.toLowerCase() === username.toLowerCase());
+    if (invitation) {
+      execFileSync('gh', ['api', `repos/${owner}/${repo}/invitations/${invitation.id}`, '-X', 'DELETE']);
+    }
+  } catch {
+    // Silently ignore if invitations endpoint fails or no invitation found
+  }
+}
+
+function createGithubRepo(repoName) {
+  try {
+    execFileSync('gh', ['repo', 'create', repoName, '--private']);
+  } catch (err) {
+    const message = (err.stderr || err.message).toString();
+    if (!/already exists/i.test(message)) throw err;
+  }
+  return `https://github.com/${githubLogin()}/${repoName}.git`;
+}
+
+const DEFAULT_REPO_NAME = 'envsync-vault';
+
+module.exports = {
+  sharedDir, loadBackupConfig, isConnected, connectRepo, pushBackup, pullBackup, fetchRemoteMerged,
+  isGhInstalled, isGhAuthenticated, githubLogin, loginInteractive, createGithubRepo, addCollaborator, removeCollaborator, DEFAULT_REPO_NAME,
+};