hotdrop 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armed Juror
+
+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,162 @@
+# HotDrop
+
+[![npm version](https://img.shields.io/npm/v/hotdrop)](https://www.npmjs.com/package/hotdrop)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)
+
+> Serverless P2P file sharing — no cloud, no installs, just a URL.
+
+Files transfer **directly between browsers** via WebRTC. The server only brokers the initial handshake — it never sees your files. Supports multiple peers per room, works across any network, and runs offline on a local LAN with zero internet usage.
+
+**[Try it live](https://hotdrop.armedjuror.in)** · [npm](https://www.npmjs.com/package/hotdrop) · [Buy me a coffee](https://buymeacoffee.com/armedjuror)
+
+---
+
+## Table of Contents
+
+- [How it works](#how-it-works)
+- [Installation](#installation)
+  - [Global CLI (local network)](#global-cli-local-network)
+  - [Self-hosted server](#self-hosted-server)
+- [CLI reference](#cli-reference)
+- [Architecture](#architecture)
+- [Features](#features)
+- [Limitations](#limitations)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## How it works
+
+1. Open the app → tap **Create Room** → share the 6-character code or QR
+2. Other devices scan the QR or enter the code
+3. A direct WebRTC connection is established between all peers
+4. Any peer can send files — recipients get an instant in-browser download prompt
+
+Files exist only in browser memory. Nothing is written to disk or stored on the server.
+
+---
+
+## Installation
+
+### Global CLI (local network)
+
+Install globally via npm to run HotDrop as a background service on your machine. All traffic stays on your LAN — zero internet data consumed.
+
+```bash
+npm install -g hotdrop
+hotdrop start
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/armedjuror/hotdrop
+cd hotdrop
+bash local_install.sh
+```
+
+Once running, open `http://<YOUR_LOCAL_IP>:5821` on any device on the same network. The QR code on the create screen automatically encodes the server's LAN IP so other devices can scan and join immediately.
+
+The UI shows a **HotDrop.local** label when connected to a local server.
+
+### Self-hosted server
+
+To run HotDrop on a VPS or cloud server (accessible over the internet):
+
+```bash
+git clone https://github.com/armedjuror/hotdrop
+cd hotdrop
+npm install
+npm start
+```
+
+Set the `PORT` environment variable if needed (defaults to `5821`). For production, place it behind a reverse proxy (nginx, Caddy) with TLS — the client requires `wss://` on HTTPS origins.
+
+---
+
+## CLI reference
+
+```
+hotdrop start      Start the server in the background (survives terminal close)
+hotdrop stop       Stop the server
+hotdrop status     Check whether the server is running
+hotdrop logs       View server logs
+hotdrop uninstall  Stop the server and remove temp files
+```
+
+---
+
+## Architecture
+
+```
+Browser A ──── WebRTC DataChannel (direct P2P) ──── Browser B
+    │                                                     │
+    │                                               Browser C
+    │                                                     │
+    └────────── WebSocket (signaling only) ───────────────┘
+                       Signaling server
+                  (never sees your files)
+```
+
+The signaling server exchanges only WebRTC handshake messages (offer/answer/ICE candidates). Once peers are connected, the server plays no further role.
+
+Each pair of peers maintains its own direct P2P connection (mesh topology). Sending a file broadcasts it to all connected peers simultaneously — each peer receives a full independent copy.
+
+---
+
+## Features
+
+- No client installs — works in any modern browser
+- Pure P2P — files never touch the server
+- Multi-peer rooms — send to multiple devices at once
+- Room grace period — rooms stay alive for 5 minutes after the last peer disconnects, allowing rejoin without recreating
+- LAN mode — run locally for zero-internet intra-network transfers
+- QR code auto-encodes the server's LAN IP when running locally
+- Installable as a PWA on iOS, Android, and desktop
+- Single-file frontend — no build step, no bundler
+
+---
+
+## Limitations
+
+- All peers must have the page open simultaneously (no store-and-forward)
+- Multi-peer upload cost: a 1 GB file sent to 3 peers uses 2 GB of upload
+- Large files (>1 GB) may be constrained by device RAM
+- No TURN relay — if NAT traversal fails, there is no fallback
+- WebRTC on iOS requires Safari 16+ or any browser on iOS 16+
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue first for significant changes so the approach can be discussed before a PR is submitted.
+
+**Guidelines:**
+
+- Keep the server minimal — `express` and `ws` are the only dependencies by design
+- The frontend is a single `index.html` with no build step — keep it that way
+- Test on at least two real devices (not just two browser tabs) before submitting
+- Follow existing code style — no linters are enforced, but consistency matters
+
+**Development setup:**
+
+```bash
+git clone https://github.com/armedjuror/hotdrop
+cd hotdrop
+npm install
+npm start
+# Open http://localhost:5821 in two tabs or on two devices on the same network
+```
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Commit your changes
+4. Open a pull request against `main`
+
+---
+
+## License
+
+[MIT](LICENSE)

package/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PID_FILE = path.join(os.tmpdir(), 'hotdrop.pid');
+const LOG_FILE = path.join(os.tmpdir(), 'hotdrop.log');
+const SERVER  = path.join(__dirname, 'signaling', 'server.js');
+
+const cmd = process.argv[2];
+
+if (cmd === 'start') {
+  if (fs.existsSync(PID_FILE)) {
+    const pid = fs.readFileSync(PID_FILE, 'utf8').trim();
+    try {
+      process.kill(Number(pid), 0);
+      console.log(`\n  HotDrop is already running (PID ${pid})`);
+      console.log(`  Run "hotdrop stop" to stop it.\n`);
+      process.exit(0);
+    } catch (_) {
+      fs.unlinkSync(PID_FILE); // stale PID
+    }
+  }
+
+  // Truncate log on fresh start so old output doesn't confuse
+  fs.writeFileSync(LOG_FILE, '');
+  const out = fs.openSync(LOG_FILE, 'a');
+
+  const child = spawn(process.execPath, [SERVER], {
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: { ...process.env }
+  });
+  fs.writeFileSync(PID_FILE, String(child.pid));
+  child.unref();
+
+  setTimeout(() => {
+    try {
+      const log = fs.readFileSync(LOG_FILE, 'utf8').trim();
+      if (log) console.log('\n' + log);
+    } catch (_) {}
+    console.log(`\n  Logs: hotdrop logs\n  Stop: hotdrop stop\n`);
+    process.exit(0);
+  }, 800);
+
+} else if (cmd === 'stop') {
+  if (!fs.existsSync(PID_FILE)) {
+    console.log('\n  HotDrop is not running.\n');
+    process.exit(0);
+  }
+  const pid = fs.readFileSync(PID_FILE, 'utf8').trim();
+  try {
+    process.kill(Number(pid), 'SIGTERM');
+    fs.unlinkSync(PID_FILE);
+    console.log(`\n  HotDrop stopped (PID ${pid}).\n`);
+  } catch (e) {
+    console.log(`\n  Could not stop process (${e.message}). Cleaning up PID file.\n`);
+    try { fs.unlinkSync(PID_FILE); } catch (_) {}
+  }
+  process.exit(0);
+
+} else if (cmd === 'status') {
+  if (!fs.existsSync(PID_FILE)) {
+    console.log('\n  HotDrop is not running.\n');
+  } else {
+    const pid = fs.readFileSync(PID_FILE, 'utf8').trim();
+    try {
+      process.kill(Number(pid), 0);
+      console.log(`\n  HotDrop is running (PID ${pid}).\n`);
+    } catch (_) {
+      console.log('\n  HotDrop is not running (stale PID).\n');
+    }
+  }
+  process.exit(0);
+
+} else if (cmd === 'logs') {
+  if (fs.existsSync(LOG_FILE)) {
+    const log = fs.readFileSync(LOG_FILE, 'utf8').trim();
+    console.log(log || '\n  Log is empty.\n');
+  } else {
+    console.log('\n  No log file found. Has HotDrop been started yet?\n');
+  }
+
+} else if (cmd === 'uninstall') {
+  // Stop if running
+  if (fs.existsSync(PID_FILE)) {
+    const pid = fs.readFileSync(PID_FILE, 'utf8').trim();
+    try { process.kill(Number(pid), 'SIGTERM'); } catch (_) {}
+    try { fs.unlinkSync(PID_FILE); } catch (_) {}
+  }
+  // Clean up log
+  try { fs.unlinkSync(LOG_FILE); } catch (_) {}
+  console.log('\n  HotDrop stopped and temp files removed.');
+  console.log('  To fully uninstall, remove the symlink:\n');
+  console.log('    sudo rm /usr/local/bin/hotdrop\n');
+  process.exit(0);
+
+} else {
+  console.log(`
+  HotDrop — peer-to-peer LAN file sharing
+
+  Usage:
+    hotdrop start      Start the server (survives terminal close)
+    hotdrop stop       Stop the server
+    hotdrop status     Check if running
+    hotdrop logs       View server logs
+    hotdrop uninstall  Stop server and clean up temp files
+`);
+}

package/local_install.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BIN_PATH="/usr/local/bin/hotdrop"
+
+echo ""
+echo "  Installing HotDrop..."
+
+# Install dependencies if needed
+if [ ! -d "$SCRIPT_DIR/node_modules" ]; then
+  echo "  Installing dependencies..."
+  cd "$SCRIPT_DIR" && npm install
+fi
+
+# Make cli.js executable
+chmod +x "$SCRIPT_DIR/cli.js"
+
+# Create symlink in /usr/local/bin
+if [ -w "/usr/local/bin" ]; then
+  ln -sf "$SCRIPT_DIR/cli.js" "$BIN_PATH"
+else
+  echo "  (sudo required to install to /usr/local/bin)"
+  sudo ln -sf "$SCRIPT_DIR/cli.js" "$BIN_PATH"
+fi
+
+echo ""
+echo "  ✓ Installed! Commands:"
+echo ""
+echo "    hotdrop start      — Start the server"
+echo "    hotdrop stop       — Stop the server"
+echo "    hotdrop status     — Check if running"
+echo "    hotdrop logs       — View logs"
+echo "    hotdrop uninstall  — Stop and clean up"
+echo ""
+echo "  Then open http://$(hostname -I 2>/dev/null | awk '{print $1}' || echo 'YOUR_LOCAL_IP'):5821 on any device."
+echo ""

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "hotdrop",
+  "version": "1.0.0",
+  "description": "P2P LAN & internet file sharing via WebRTC — no cloud, no installs, just a URL",
+  "main": "signaling/server.js",
+  "bin": {
+    "hotdrop": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "local_install.sh",
+    "signaling/server.js",
+    "signaling/package.json",
+    "public/"
+  ],
+  "scripts": {
+    "start": "node signaling/server.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "webrtc",
+    "p2p",
+    "file-transfer",
+    "lan",
+    "local",
+    "hotdrop",
+    "file-sharing",
+    "peer-to-peer"
+  ],
+  "author": "armedjuror",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/armedjuror/hotdrop.git"
+  },
+  "homepage": "https://github.com/armedjuror/hotdrop#readme",
+  "bugs": {
+    "url": "https://github.com/armedjuror/hotdrop/issues"
+  },
+  "dependencies": {
+    "express": "^5.2.1",
+    "ws": "^8.18.2"
+  }
+}

package/public/icon-192.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 192" width="192" height="192">
+  <rect width="192" height="192" fill="#0a0a0a" rx="32"/>
+  <rect x="16" y="16" width="160" height="160" fill="none" stroke="#222" stroke-width="1"/>
+  <!-- Arrow up -->
+  <path d="M96 52 L72 80 L84 80 L84 100 L108 100 L108 80 L120 80 Z" fill="#e8ff47"/>
+  <!-- Horizontal line -->
+  <rect x="56" y="112" width="80" height="4" fill="#e8ff47" rx="2"/>
+  <!-- Dots -->
+  <circle cx="60" cy="130" r="4" fill="#47c8ff"/>
+  <circle cx="96" cy="130" r="4" fill="#47c8ff"/>
+  <circle cx="132" cy="130" r="4" fill="#47c8ff"/>
+  <!-- Text -->
+  <text x="96" y="158" text-anchor="middle" font-family="monospace" font-size="13" fill="#555" letter-spacing="2">LOCAL</text>
+</svg>

package/public/icon-512.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <rect width="512" height="512" fill="#0a0a0a" rx="80"/>
+  <rect x="40" y="40" width="432" height="432" fill="none" stroke="#222" stroke-width="2"/>
+  <path d="M256 130 L190 210 L222 210 L222 270 L290 270 L290 210 L322 210 Z" fill="#e8ff47"/>
+  <rect x="140" y="300" width="232" height="10" fill="#e8ff47" rx="5"/>
+  <circle cx="160" cy="348" r="12" fill="#47c8ff"/>
+  <circle cx="256" cy="348" r="12" fill="#47c8ff"/>
+  <circle cx="352" cy="348" r="12" fill="#47c8ff"/>
+  <text x="256" y="418" text-anchor="middle" font-family="monospace" font-size="36" fill="#333" letter-spacing="6">LOCAL</text>
+</svg>