lanp2p (netdrop) 🚀

A terminal-based peer-to-peer (P2P) file transfer tool for local networks. It enables devices on the same Wi-Fi or Ethernet network to automatically discover each other and transfer files or directories directly using UDP discovery and TCP socket streaming.

No external servers, no cloud storage, no account registration—100% direct local transfers.

---

✨ Features

• 🔍 Zero-Config Peer Discovery: Uses UDP broadcast beacons to automatically discover online devices on your LAN.
• ⚡ High-Speed TCP Streaming: Direct peer-to-peer data pipeline utilizing the full bandwidth of your local network.
• 📁 File & Directory Support: Seamlessly send single files or entire folders (directories are automatically packed and unpacked).
• 🔒 SHA-256 Cryptographic Verification: Computes and validates cryptographic checksums on both ends to ensure 100% data integrity.
• 🛡️ Built-in Security:
  • Filename sanitization to protect against directory traversal and path manipulation attacks.
  • Safe archive extraction preventing Zip/Tar Slip vulnerabilities.
  • Interactive approval prompts before accepting incoming transfers.
  • Automatic collision-free file naming (e.g. file (1).ext).
• 🎨 Beautiful Terminal UI: Powered by rich, featuring real-time progress bars, download/upload speeds in MB/s, ETA countdowns, and formatted tables.
• 📦 Pip Package Ready: Standard pyproject.toml package structure, ready to install locally or publish to PyPI.

---

📥 Installation

1. From Local Source (Editable Mode)

git clone https://github.com/example/lanp2p.git
cd lanp2p
pip install -e .

This installs two executable commands: lanp2p and netdrop.

2. Standard Pip Install

pip install .

---

🚀 Quick Start & Usage

1. Start Receiving Files (listen)

Run this on the machine that will receive files:

lanp2p listen

Options:

• -y, --yes: Automatically accept incoming transfers without prompting.
• -d, --save-dir <path>: Directory where downloaded files are saved (default: ./downloads).
• -p, --port <number>: TCP transfer port (default: 50006).
• -n, --name <custom_name>: Set custom peer name visible on the network.

Example:

lanp2p listen -y -d ~/Downloads

---

2. Send a File or Folder (send)

Interactive Mode (Auto-Discover Peers)

Simply run send with the target file:

lanp2p send presentation.pdf

lanp2p will scan the local network for 2.5 seconds, display a list of online peers, and prompt you to pick one:

Found 2 peer(s):
+---+----------------------+----------------+----------+---------+
| # | Peer Name            | IP Address     | TCP Port | OS      |
+---+----------------------+----------------+----------+---------+
| 1 | alice@MacBook-Pro    | 192.168.1.45   | 50006    | Darwin  |
| 2 | bob@Ubuntu-Desktop   | 192.168.1.88   | 50006    | Linux   |
+---+----------------------+----------------+----------+---------+
Select a peer number or enter target IP directly [1]: 1

Direct IP Mode

If you already know the recipient's IP (or if UDP broadcast is disabled by router AP isolation):

# Send a file
lanp2p send dataset.csv --to 192.168.1.45

# Send an entire folder
lanp2p send ./my_project --to 192.168.1.45

---

3. Scan Network Peers (peers)

List all active peers currently advertising on your local network:

lanp2p peers --ping

Output:

+---+----------------------+----------------+----------+---------+----------+
| # | Peer Name            | IP Address     | TCP Port | OS      | Latency  |
+---+----------------------+----------------+----------+---------+----------+
| 1 | cajetan@Cajetans-PC  | 192.168.8.222  | 50006    | Windows | 1.2 ms   |
| 2 | lab@Server01         | 192.168.8.10   | 50006    | Linux   | 0.8 ms   |
+---+----------------------+----------------+----------+---------+----------+

---

4. Test Connectivity (ping)

Check TCP connectivity and latency to a peer's receiver port:

lanp2p ping 192.168.8.222

---

5. Network Diagnostics (info)

View local network adapters, detected IPs, and broadcast addresses:

lanp2p info

---

🛠️ Architecture & Protocol Design

1. Peer Discovery (UDP Port 50005)

Every 2 seconds, the DiscoveryBeaconService broadcasts a UDP datagram to 255.255.255.255 and subnet broadcast addresses:

{
  "magic": "LANP2P_BEACON_V1",
  "peer_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "cajetan@Cajetans-PC",
  "port": 50006,
  "system": "Windows",
  "version": "1.0",
  "ips": ["192.168.8.222"],
  "timestamp": 1727166000.0
}

The DiscoveryListener maintains a thread-safe registry of active peers, expiring inactive peers after 6 seconds.

2. File Transfer Framing (TCP Port 50006)

All TCP control messages are framed using a 4-byte big-endian length prefix followed by a UTF-8 JSON payload:

+---------------------------+-----------------------------------+
| 4-byte uint32 (len = N)   | N bytes UTF-8 JSON control string |
+---------------------------+-----------------------------------+

Transfer Flow:

Sender                                            Receiver (lanp2p listen)
  |                                                          |
  | -------- 1. TCP Connect (Port 50006) ------------------> |
  |                                                          |
  | -------- 2. TRANSFER_INIT (name, size, sha256) --------> |
  |                                                          | [Prompt user / auto-accept]
  | <------- 3. TRANSFER_RESP (status: ACCEPTED) ----------- |
  |                                                          |
  | ======== 4. Binary Data Stream (64 KB chunks) ========> | [Compute SHA-256 while writing .part]
  |                                                          |
  |                                                          | [Verify SHA-256 == expected]
  |                                                          | [Atomic rename .part -> final]
  | <------- 5. TRANSFER_ACK (status: SUCCESS) ------------- |
  |                                                          |

---

📦 How to Build and Publish to PyPI

1. Build Source Distribution and Wheel

Make sure build is installed:

pip install build
python -m build

This produces:

• dist/lanp2p-0.1.0-py3-none-any.whl
• dist/lanp2p-0.1.0.tar.gz

2. Publish to PyPI with Twine

Install twine:

pip install twine

Upload to TestPyPI first (recommended):

python -m twine upload --repository testpypi dist/*

Upload to official PyPI:

python -m twine upload dist/*

---

🛡️ Firewall Configuration

If peers cannot discover each other or connect:

• Windows: Allow Python / lanp2p through Windows Defender Firewall, or allow inbound TCP port 50006 and UDP port 50005.
• Linux (UFW):

  sudo ufw allow 50005/udp
  sudo ufw allow 50006/tcp
  

• Wi-Fi AP Isolation: Some public Wi-Fi networks (hotels, cafes) block client-to-client traffic. On such networks, connecting both devices to a mobile hotspot or specifying direct IPs bypasses discovery limitations.

---

🧪 Running Automated Tests

Run the complete test suite:

python -m unittest discover tests

---

📄 License

This project is licensed under the MIT License.