rdrop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rshare contributors
+
+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,264 @@
+# rshare
+
+Send files and folders from one computer to another (Windows, macOS or Linux) with
+one command on each side: across the room or across the country. Fast, end-to-end
+encrypted, no accounts.
+
+```text
+computer A                                  computer B
+$ rshare add .
+$ rshare share
+    rshare receive 04fccatxfc…   ──────►    $ rshare receive 04fccatxfc…
+                                            ✓ Received 505 files (1.0 GB) in 9.4s
+```
+
+## Install
+
+```sh
+npm install -g rdrop
+```
+
+The package is called `rdrop` on npm, and it installs the `rshare` command. This needs
+Node.js 16 or newer. The package contains a small native program for Windows,
+macOS and Linux (x64 and ARM), and Node is only used to start it. `pip install rdrop` is
+planned.
+
+## Use
+
+On the computer that has the files:
+
+```sh
+cd my-project
+rshare add .               # stage the folder you're in
+rshare add ~/notes.pdf     # stage more files or folders, from anywhere
+rshare share
+```
+
+`rshare share` prints a command like `rshare receive 04fccatxfcqn51s22qkh0x33crye0sbz00003g8g`
+and copies it to your clipboard. Send it to the other person any way you like (chat, email),
+and they run it on their computer:
+
+```sh
+rshare receive 04fccatxfcqn51s22qkh0x33crye0sbz00003g8g
+```
+
+The files land in the folder where they ran the command (or in `--out <folder>`).
+
+On the same network the two computers connect directly. To send to someone on a
+**different network** (a friend at their home, say), you need a relay. Set it up once, as
+described in [Sharing over the internet](#sharing-over-the-internet).
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `rshare add <path>...` | Stage files or folders. `.` is the current folder. Wildcards work (`rshare add *.pdf`), even in cmd and PowerShell. |
+| `rshare list` | Show what's staged, with sizes. |
+| `rshare remove <path or #>` | Unstage something, by path or by its number in `list`. |
+| `rshare clear` | Unstage everything. |
+| `rshare share [path...]` | Share the staged items, or only the paths given (`rshare share movie.mp4`). |
+| `rshare receive <code>` | Download everything the other computer is sharing. |
+| `rshare config` | Show settings. `rshare config relay <address>` sets the relay to use. |
+| `rshare relay` | Run a relay server (see below). |
+
+| Option | |
+|---|---|
+| `share --keep` | Keep sharing after the first download. By default a code works once. |
+| `share --relay <address>` | Use this relay for this share. |
+| `share --local` | Don't use the relay this time. |
+| `share --relay-only` | Skip the direct connection and always go through the relay. |
+| `share --port <n>` | Port to listen on locally (default 7878, or any free port if that's taken). |
+| `share --host <ip>` | Listen only on this local address. |
+| `receive --out <dir>` | Where to save files. |
+| `receive --overwrite` | Replace files that differ instead of saving the new copy as `name (1).ext`. |
+| `add/share --force` | Allow sharing your home folder or another broad folder. |
+
+### Good to know
+
+- **Interrupted transfers resume.** Run the same `rshare receive` command again. Finished files
+  are skipped and a half-finished file continues where it stopped. This also works with a new
+  code if the sender restarted `rshare share`.
+- **Nothing gets overwritten.** If the receiver already has a different file with the same
+  name, the new one is saved as `name (1).ext`. Identical files are skipped.
+- **Safe folders only.** `rshare add .` won't share your home folder (where a new terminal
+  opens) unless you add `--force`, and it never shares a whole drive or an operating-system
+  folder.
+- **Left out:** shortcuts/symlinks and OS clutter (`.DS_Store`, `Thumbs.db`, `desktop.ini`).
+  File names that Windows can't store (`what?.txt` from a Mac) are adjusted on arrival.
+- **Firewalls (same-network sharing).** The first time you share on Windows, Windows Defender
+  Firewall asks whether to allow rshare: allow it on **Private networks**. If your Wi-Fi is
+  marked as a *Public* network, other computers on it can't connect; switch it to Private in
+  Settings → Network & internet. macOS may ask to accept incoming connections: click Allow.
+  Sharing through a relay needs no firewall changes, because both computers connect out.
+
+## Sharing over the internet
+
+Two computers in different homes usually can't connect to each other: home routers block
+incoming connections, and many internet providers put whole neighborhoods behind one shared
+address (carrier-grade NAT). The fix that always works is a **relay**: a small server both
+computers can reach, which passes the data between them. Tools like croc and AnyDesk work
+the same way.
+
+The relay is built into rshare (`rshare relay`). You run it once on a server with a public
+address, then point rshare at it:
+
+```sh
+rshare config relay wss://your-relay.example.com    # on each computer that shares
+```
+
+That's all. `rshare share` now prints a code that works from anywhere, and **the receiver
+doesn't configure anything**, because the code says where the relay is. When both
+computers turn out to be on the same network, they still connect directly, which is faster
+and doesn't touch the relay.
+
+The relay can't read anything. The encryption runs end to end between the two computers,
+straight through it, and the relay never sees the code's secret. It does see both
+computers' IP addresses, when a transfer happens and how big it is.
+
+### Where to run the relay
+
+Pick whichever suits you. The relay uses very little memory or CPU. What it does use is
+bandwidth: every byte sent goes through it once in and once out.
+
+**A. Any small Linux server.** This means a VPS ($4–6/month at DigitalOcean, Hetzner, Vultr
+and others), the free Oracle Cloud VM, or a home server with a port forwarded.
+
+```sh
+# from this repository, after `npm run build` (use linux-arm64 for ARM servers):
+scp packages/npm/dist/linux-x64/rshare you@SERVER:/tmp/rshare
+ssh you@SERVER
+sudo install -m 755 /tmp/rshare /usr/local/bin/rshare
+rshare relay                      # try it; Ctrl+C to stop
+```
+
+To keep it running and have it start on boot, copy
+`deploy/relay/rshare-relay.service` (in the source repository) to
+`/etc/systemd/system/` and run `sudo systemctl enable --now rshare-relay`. Then open port
+8080 in the provider's firewall ("security group"), and on your computer:
+
+```sh
+rshare config relay ws://SERVER_IP:8080
+```
+
+**B. Render, free, with no server to manage.** Push this repository to GitHub, then on
+[render.com](https://render.com) choose **New → Blueprint** and pick the repository. It reads
+`render.yaml`, builds the relay and gives you an address like
+`https://rshare-relay-abcd.onrender.com`. Then run:
+
+```sh
+rshare config relay wss://rshare-relay-abcd.onrender.com
+```
+
+Free Render services go to sleep after about 15 minutes without traffic. The first share
+after that waits up to a minute while it wakes up, and the free plan has a monthly
+bandwidth allowance. Any other host that runs Docker images and supports WebSockets works
+too (Railway, Fly.io, Koyeb…).
+
+**C. Docker, anywhere:**
+
+```sh
+docker build -f deploy/relay/Dockerfile -t rshare-relay .
+docker run -d -p 8080:8080 --restart unless-stopped rshare-relay
+```
+
+### Make it the default for everyone
+
+Put the relay's address in the `DEFAULT_RELAY` file, run `npm run build`,
+and publish. Every copy of rshare installed from that build uses your relay automatically:
+nobody runs `rshare config`, and share codes stay short because they don't need to spell out
+the address.
+
+### Keeping your relay to yourself
+
+An open relay lets anyone relay through it. They still can't read anyone else's files, but
+they would use your bandwidth. To restrict it, start it with a key and include the key in
+the address:
+
+```sh
+rshare relay --key s3cret                   # or set RSHARE_RELAY_KEY
+rshare config relay wss://your-relay.example.com/?key=s3cret
+```
+
+The key travels inside share codes, so receivers don't need to know it. (If you publish a
+build with the key in `DEFAULT_RELAY`, assume it's public.)
+
+### No server at all?
+
+If both people install [Tailscale](https://tailscale.com) (free for personal use), their
+computers behave as if they were on the same network. rshare then connects directly without
+a relay.
+
+## Security
+
+- Each `rshare share` creates a new random 128-bit secret. It exists only inside the code.
+  Without it nobody can download anything, and it can't be guessed.
+- Everything is encrypted with TLS 1.3. Both sides also prove they know the secret, tied to
+  that particular encrypted connection. So nobody in the middle (including a relay) can read
+  the traffic or pretend to be the sender. (Details: `core/internal/transfer/secure.go`.)
+- On the local network, the sender listens only on private addresses (192.168.x.x,
+  10.x.x.x, 172.16–31.x.x, 100.64–127.x.x for VPNs like Tailscale, 169.254.x.x for direct
+  cables), never on a public internet address. Across networks it connects *out* to the
+  relay; nothing is opened up on your router.
+- The relay knows a share only by a one-way hash of its secret, so it can't work the secret
+  out. Someone who learned that hash could knock on the share, but without the secret the
+  sender turns them away.
+- A receiver can only download what was shared. It can't browse the sender's disk.
+  Incoming file names are checked so a malicious sender can't write outside the
+  destination folder.
+- While a share is running, treat the code like a password.
+
+## How it works, and why it's fast
+
+- The core is one native program written in Go: no runtime to install, about 8 MB, and it
+  starts instantly. The npm package is a thin launcher for it, and the pip package will wrap
+  the same program.
+- On the same network the computers connect directly, so the speed is set by your network
+  and disks. Over loopback it moved 1 GB (encrypted) at about 500 MB/s. Through a relay, the
+  limit is usually the sender's upload speed.
+- The code contains all of the sender's local addresses plus the relay. The receiver tries
+  the direct addresses at once and the relay a moment later, then uses whichever works first.
+  Nobody has to work out which IP address to use.
+- Big files stream in large chunks. Folders full of small files are fetched in batches over
+  4 parallel connections, so they don't crawl.
+- If the connection drops, the receiver reconnects and resumes mid-file by itself.
+- The relay speaks WebSocket, so it can sit behind ordinary HTTPS web hosting on port 443.
+  Even strict office and campus networks allow that.
+
+## Develop
+
+You need Go 1.22+ and Node.js 16+.
+
+```sh
+npm run build:dev    # build for this machine only
+npm test             # Go unit and end-to-end tests (including the relay)
+npm run build        # cross-compile all 6 platforms into packages/npm/dist
+npm run pack         # build, then create packages/npm/rshare-<version>.tgz
+```
+
+To try the packed tarball: `npm i -g ./packages/npm/rdrop-0.1.0.tgz`.
+To release: bump `VERSION`, run `npm run build`, then `cd packages/npm && npm publish`.
+
+```text
+core/                  Go source of the rshare program (all the logic)
+  cmd/rshare/          entry point
+  internal/cli/        commands and output
+  internal/config/     per-user settings (which relay to use)
+  internal/relay/      the relay server, and the client side senders/receivers use
+  internal/stage/      staging list, and the "don't share my whole drive" guard
+  internal/transfer/   share codes, encryption, sender, receiver
+  internal/ui/         colors, progress bar, clipboard
+deploy/relay/          Dockerfile and systemd service for running a relay
+packages/npm/          npm package: launcher + prebuilt binaries (dist/ is generated)
+packages/python/       pip package skeleton (not published yet)
+scripts/build.mjs      cross-compiles core/ for every platform
+VERSION                one version number for every package
+DEFAULT_RELAY          relay address built into every copy (empty = none)
+render.yaml            one-click relay deployment on Render
+```
+
+## Roadmap
+
+- `pip install rdrop` (one wheel per platform; the skeleton is in `packages/python`)
+- Direct connections between different networks (NAT hole punching) where routers allow it,
+  so the relay is only the fallback
+- One npm package per platform, so an install downloads only the binary it needs

package/bin/rshare.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin launcher: all the real work happens in the native rshare binary.
+
+const { spawn } = require('child_process');
+const { binaryPath } = require('../lib/binary');
+
+let bin;
+try {
+  bin = binaryPath();
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' });
+
+// Ctrl+C reaches the binary directly (it shares the terminal) and the binary
+// shuts down cleanly on its own, so the launcher just waits for it.
+process.on('SIGINT', () => {});
+for (const sig of ['SIGTERM', 'SIGHUP']) {
+  process.on(sig, () => child.kill(sig));
+}
+
+child.on('error', (err) => {
+  console.error(`rshare: couldn't start ${bin}: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code === null ? 1 : code);
+});

package/install.js

@@ -0,0 +1,11 @@
+'use strict';
+
+// Runs after `npm install` to check the binary for this machine is present
+// and executable. It never fails the install: the launcher repeats these
+// checks and explains any problem when rshare is actually run.
+
+try {
+  require('./lib/binary').binaryPath();
+} catch (err) {
+  console.warn(String((err && err.message) || err));
+}

package/lib/binary.js

@@ -0,0 +1,62 @@
+'use strict';
+
+// Finds the prebuilt rshare binary for this machine. scripts/build.mjs puts
+// one per platform under dist/<platform>-<arch>/ before the package is
+// published.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SUPPORTED = ['win32-x64', 'win32-arm64', 'darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64'];
+
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function bundledPath() {
+  const exe = process.platform === 'win32' ? 'rshare.exe' : 'rshare';
+  return path.join(__dirname, '..', 'dist', platformKey(), exe);
+}
+
+// A package packed on Windows loses the executable bit on everything that
+// isn't listed in "bin", so restore it. If the install folder is read-only
+// (a global install made as root), run a private copy from the user's cache
+// folder instead.
+function ensureExecutable(file) {
+  if (process.platform === 'win32') return file;
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return file;
+  } catch {}
+  try {
+    fs.chmodSync(file, 0o755);
+    return file;
+  } catch {}
+  const { version } = require('../package.json');
+  const dir = path.join(os.homedir(), '.cache', 'rshare', version);
+  const copy = path.join(dir, 'rshare');
+  try {
+    if (fs.statSync(copy).size === fs.statSync(file).size) return copy;
+  } catch {}
+  fs.mkdirSync(dir, { recursive: true });
+  fs.copyFileSync(file, copy);
+  fs.chmodSync(copy, 0o755);
+  return copy;
+}
+
+function binaryPath() {
+  if (process.env.RSHARE_BINARY) return process.env.RSHARE_BINARY;
+  const key = platformKey();
+  const file = bundledPath();
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      SUPPORTED.includes(key)
+        ? `rshare: the program for ${key} is missing from this install (${file}).\nReinstall with: npm i -g rdrop`
+        : `rshare: ${key} isn't supported yet (supported: ${SUPPORTED.join(', ')}).`
+    );
+  }
+  return ensureExecutable(file);
+}
+
+module.exports = { binaryPath, platformKey, SUPPORTED };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "rdrop",
+  "version": "0.1.0",
+  "description": "Send files and folders between computers on the same network: fast, encrypted, one command.",
+  "keywords": [
+    "file-sharing",
+    "file-transfer",
+    "share",
+    "send",
+    "lan",
+    "p2p",
+    "ftp",
+    "airdrop",
+    "cli"
+  ],
+  "license": "MIT",
+  "bin": {
+    "rshare": "bin/rshare.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "dist/",
+    "install.js"
+  ],
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}