Metadata-Version: 2.4
Name: servepass
Version: 0.4.0
Summary: LAN file server with HTTPS and token auth. Like python -m http.server but with auth
Author-email: Fulvio Favilla <fulvio@fulvio.sh>
License-Expression: MIT
Project-URL: Homepage, https://github.com/fulviofavilla/servepass
Project-URL: Repository, https://github.com/fulviofavilla/servepass
Project-URL: Issues, https://github.com/fulviofavilla/servepass/issues
Keywords: http,https,server,lan,file-sharing,auth,privacy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tls
Requires-Dist: cryptography>=3.1; extra == "tls"
Provides-Extra: qr
Requires-Dist: qrcode; extra == "qr"
Dynamic: license-file

# servepass

Serve files on your LAN over HTTPS with a token. That's it.

```
pipx install servepass
servepass
```

---

You know `python -m http.server`. It's great for quick file sharing on a local network. The problem is it has zero authentication, so anyone on the same network can grab whatever you're serving.

`servepass` fixes that. Same zero-config philosophy, but encrypted and with a token-protected URL. Run it, get a link, share it. No accounts, no cloud, no telemetry.

## Install

```bash
pipx install servepass
```

Or with pip:

```bash
pip install servepass
```

Requires Python 3.8+. No required dependencies.

HTTPS needs a way to create a certificate. servepass uses the `openssl` command if it's on your system (it is on most Linux and macOS machines). If it isn't, for example on Windows, install the optional extra:

```bash
pipx install "servepass[tls]"
```

## Usage

```bash
# Serve current directory
servepass

# Serve a specific path
servepass ./downloads

# Custom port
servepass --port 9090

# Fixed token (at least 16 characters recommended)
servepass --token my-long-fixed-token

# Your own certificate, e.g. from mkcert (no browser warning)
servepass --cert cert.pem --key key.pem

# Limit upload size (default 4G, 0 = no limit)
servepass --max-upload 500M

# Plain HTTP, no encryption
servepass --http

# No authentication
servepass --no-auth
```

Every time you run servepass, a fresh token is generated. You get a URL and an optional QR code in the terminal:

```
  Serving:  /home/user/downloads
  Network:  https://192.168.1.42:8080/?token=Xq3vT9kR2mW8pL5nB7cY1a
  Token:    Xq3vT9kR2mW8pL5nB7cY1a
  SHA-256:  6A:1F:0C:93:E2:5B:7D:48:AA:10:C4:3E:9F:22:B8:71
            05:DE:6C:18:F4:A9:33:57:0B:E7:92:4D:C6:81:2A:F0
            Your browser will warn about the self-signed certificate.
            It's safe to continue if it shows this same fingerprint.
  Uploads:  up to 4 GiB

  Ctrl+C to stop
```

Open the URL in any browser on your network and you're in. Scan the QR code to open it directly on your phone. Once you open the link, the browser keeps the token in a cookie and drops it from the address bar, so it doesn't end up in your history or in links you copy.

## HTTPS and the certificate warning

servepass serves HTTPS by default, so nobody else on the network can read the token or the files you transfer.

The first time you run it, servepass creates a self-signed certificate for your machine's LAN address and keeps it in your config folder (`~/.config/servepass` on Linux, `~/Library/Application Support/servepass` on macOS, `%APPDATA%\servepass` on Windows). Browsers don't know this certificate, so they show a warning the first time you connect.

To check the connection is really to your machine, open the certificate details in the browser (click the warning or the padlock icon) and compare its SHA-256 fingerprint with the one servepass printed. If they match, continue. If they don't, someone may be intercepting the connection. Because the certificate is reused, each device only has to do this once for each network address.

If you'd rather not see the warning at all, create a locally trusted certificate with [mkcert](https://github.com/FiloSottile/mkcert) and pass it with `--cert` and `--key`.

If you type `http://` by mistake, servepass redirects you to `https://`.

## Using it from scripts

Pass the token as a header instead of in the URL:

```bash
# download
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" https://192.168.1.42:8080/file.zip -O

# upload
curl --cacert cert.pem -H "Authorization: Bearer $TOKEN" -F "file=@photo.jpg" https://192.168.1.42:8080/
```

`cert.pem` is the certificate servepass created in your config folder. `?token=...` in the URL also still works.

## What you can do

**Download files on your phone without cables**
Serve a folder, scan the QR code on your iPhone or Android, and grab whatever you need directly from the browser. Works with any file type: PDFs, photos, videos, zip archives.

**Send photos from your phone to your computer**
Open the URL on your phone, use the upload form at the top of the page, and the file lands directly in the served folder on your machine. No AirDrop, no cloud, no cable. Uploads never overwrite an existing file: a second `photo.jpg` is saved as `photo (1).jpg`.

**Share documents with someone on the same network**
Run servepass in a folder with the files you want to share. Send the link. They open it in any browser and download what they need.

## QR code

The QR code is printed automatically if the `qrcode` package is installed:

```bash
pipx install "servepass[qr]"      # or both: "servepass[tls,qr]"
```

Without it, servepass works normally and just shows the URL.

## Security

* Traffic is encrypted with TLS 1.2+ (unless you use `--http`).
* Tokens are 128-bit random values, so they can't be guessed.
* After the first visit the token lives in an `HttpOnly`, `SameSite=Lax` cookie, not in the URL.
* Uploads are only accepted from the servepass page itself, not from other websites.
* Uploads can't be written outside the served folder and never replace existing files.
* File names in the listing are escaped, so a file called `<script>...` is just text.
* Uploads are streamed to disk, and a size limit applies (`--max-upload`).

## Known limitations

* The certificate is self-signed, so browsers warn on first connect. Check the fingerprint (see above) or use `--cert` with a trusted certificate.
* Anyone who has the link has full read and upload access to the served folder. Only share it with people you trust.
* If servepass can't create a certificate (no `openssl` and no `servepass[tls]`), it falls back to plain HTTP and prints a warning.
* Symlinks inside the served folder are followed when downloading, like `python -m http.server`.

## Who this is for

* You're on a trusted LAN (home, office, workshop) and want to share files quickly
* You want to transfer files to and from your phone without cables or cloud storage
* You don't want to expose an unauthenticated HTTP server to everyone on the network
* You want something lightweight with zero setup time

## License

MIT
