Metadata-Version: 2.4
Name: lanp2p
Version: 0.1.0
Summary: A terminal-based peer-to-peer file transfer tool for local networks using TCP and UDP
Author-email: Cajetan <cajetandsouza02@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/example/lanp2p
Project-URL: Repository, https://github.com/example/lanp2p
Project-URL: Issues, https://github.com/example/lanp2p/issues
Keywords: p2p,file-transfer,networking,cli,terminal,airdrop,udp-discovery,tcp-streaming
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# lanp2p (netdrop) 🚀

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Terminal UI: Rich](https://img.shields.io/badge/UI-Rich-magenta.svg)](https://github.com/Textualize/rich)

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)
```bash
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
```bash
pip install .
```

---

## 🚀 Quick Start & Usage

### 1. Start Receiving Files (`listen`)
Run this on the machine that will receive files:

```bash
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:**
```bash
lanp2p listen -y -d ~/Downloads
```

---

### 2. Send a File or Folder (`send`)

#### Interactive Mode (Auto-Discover Peers)
Simply run `send` with the target file:
```bash
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):
```bash
# 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:

```bash
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:

```bash
lanp2p ping 192.168.8.222
```

---

### 5. Network Diagnostics (`info`)
View local network adapters, detected IPs, and broadcast addresses:

```bash
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:

```json
{
  "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:
```bash
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`:
```bash
pip install twine
```

Upload to TestPyPI first (recommended):
```bash
python -m twine upload --repository testpypi dist/*
```

Upload to official PyPI:
```bash
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)**:
  ```bash
  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:
```bash
python -m unittest discover tests
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
