lan-file-transfer - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #machine-learning #rust #macos #nodejs #java #windows #cli #awesome-list #ios #openai

lan-file-transfer

(★ 291)

Local LAN file transfer desktop app with user/group permissions and audit logs.

파일 탐색기

최종 버전 다운로드 (.zip)

- OPEN_SOURCE_AUDIT.md
- - admin.html
  - admin.js
  - styles.css
  - user.html
  - user.js
- __init__.py
- __main__.py
- api.py
- audit.py
- auth.py
- config.py
- desktop.py
- logging_config.py
- security.py
- server.py
- storage.py
- build_exe.ps1
- test_api.py
- test_audit.py
- test_auth.py
- test_config.py
- test_desktop.py
- test_frontend_contract.py
- test_logging_config.py
- test_release_metadata.py
- test_server.py
- test_storage.py
.gitattributes
.gitignore
AGENTS.md
LANFileTransfer.spec
LICENSE
README.ja.md
README.md
README.zh-CN.md
RELEASE_NOTES.md
requirements.txt
version_info.txt

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/NextWeb4/lan-file-transfer

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd lan-file-transfer

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Python

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

.\.venv\Scripts\python.exe -m pip install --upgrade pip

requirements.txt 등에 명시된 파이썬 라이브러리를 설치합니다.

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

requirements.txt 등에 명시된 파이썬 라이브러리를 설치합니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
  <a href="README.md"><img src="https://img.shields.io/badge/English-0969da?style=flat-square" alt="English"></a>
  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-c8102e?style=flat-square" alt="简体中文"></a>
  <a href="README.ja.md"><img src="https://img.shields.io/badge/%E6%97%A5%E6%9C%AC%E8%AA%9E-8250df?style=flat-square" alt="日本語"></a>
</p>

# LAN File Transfer

A Windows desktop file-sharing server with a Tkinter launcher, FastAPI backend, browser clients, role/group permissions, and an auditable local data model.

![Last commit](https://img.shields.io/github/last-commit/NextWeb4/lan-file-transfer?style=flat-square)
![Repository size](https://img.shields.io/github/repo-size/NextWeb4/lan-file-transfer?style=flat-square)
![GitHub stars](https://img.shields.io/github/stars/NextWeb4/lan-file-transfer?style=flat-square)
![Python and FastAPI](https://img.shields.io/badge/Python-FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)
![MIT License](https://img.shields.io/github/license/NextWeb4/lan-file-transfer?style=flat-square)

## Overview

The Tkinter window starts a local uvicorn service, shows user/admin URLs and QR codes, and lets you select the save directory. Phones, tablets, and computers on the same trusted Wi-Fi or LAN can then upload, browse, download, and package files from native HTML/CSS/JavaScript pages.

The service listens on `0.0.0.0` by default. This makes LAN access possible and also exposes the service to every reachable network. Run it only on a trusted network.

## Features

- Streams uploaded bytes without transcoding, recompression, image/video rewriting, EXIF changes, or extension changes.
- Stores size and SHA-256; attempts to preserve browser-provided `File.lastModified` values.
- Supports raw downloads, single-file ZIP, selected/batch ZIP, search, and server-side sorting.
- Uses guest, user, and admin roles. Guests see only files in the `public` group.
- Signed-in users can upload and delete their own files; admins manage all files, users, groups, visibility, and audit history.
- Creates built-in `public` and `everyone` groups for a new save directory.
- Creates an initial administrator account: `admin / 12345678`.
- Recursively redacts password, token, session, authorization, cookie, and secret fields from audit metadata.
- Provides Chinese/English browser UI with the preference stored in `localStorage`.
- Uses a Tkinter desktop lifecycle controller rather than a background system service.

**Change the default administrator password immediately after first launch.** The default password exists only to initialize a new local save directory.

## Install and Run

### Use a Windows release

[GitHub Release v1.0.0](https://github.com/NextWeb4/lan-file-transfer/releases/tag/v1.0.0) provides three assets:

- `LANFileTransfer.exe`: one-file Windows application;
- `lan-file-transfer-v1.0.0-windows.zip`: portable archive containing the executable;
- `SHA256SUMS.txt`: SHA-256 values for the published files.

Verify the EXE or ZIP against `SHA256SUMS.txt`, then run `LANFileTransfer.exe`. No installer or background service is created. The executable is not digitally signed, so Windows may show an unknown-publisher warning.

### Run from source

```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m lan_transfer.desktop
```

The desktop app displays two addresses:

- **User URL** for guests and ordinary users.
- **Admin URL** for administrator sign-in and management.

Wait until the desktop status reads `Running`, then open a URL or scan its QR code from a device on the same LAN.

## Typical Workflow

1. Start the desktop app and choose a save directory.
2. Open the Admin URL and sign in with the initial account on a new directory.
3. Change the administrator password before sharing the User URL.
4. Create individual users or up to 200 ordinary users in one validated batch; create groups and assign memberships.
5. Upload files or folders and choose their visibility groups.
6. Use search/sort and raw or ZIP download from another LAN device.
7. Review audit events for login, logout, upload, download, delete, permission, account, and group changes.

Mobile browsers do not always apply an HTTP `Last-Modified` value to the downloaded file on disk. Use ZIP download when preserving the archive entry mtime is important.

## Permission Model

- Guests can list/download only `public` files and cannot upload or delete.
- Ordinary users can see files assigned to their groups, upload files, and delete only their own uploads.
- Admins can manage accounts/groups, set file `allowed_groups`, inspect audits, and delete all files.
- The built-in `public` and `everyone` groups and the built-in `admin` account cannot be deleted.
- Deleting a user transfers that user's existing files to `admin` so a future account with the same name cannot inherit deletion rights.
- A group cannot be deleted while any user or file references it.

User and administrator endpoints are deliberately separate. A same-origin admin cookie must never enlarge what the User page can list or download.

## Storage and Integrity

The selected save directory contains uploaded files and local control data:

```text
manifest.json
.lan-transfer-auth.json
.lan-transfer-audit.jsonl
```

These control names, their temporary variants, and unsafe absolute/parent paths are reserved by path validation. Uploads use chunked `.part` files, size verification, SHA-256, nonconflicting names, mtime application, and atomic publication. Manifest and auth updates use hidden randomized temporary files and atomic replacement.

Strongly audited operations are transactional:

- a pending upload is invisible until its audit entry and manifest publication both succeed;
- audit failure rolls back login/logout, password, account, group, upload, delete, and permission changes;
- deletion uses a recoverable tombstone until manifest and audit work can commit;
- unsafe or stale manifest paths are revalidated before list, download, ZIP, delete, or rollback use.

## Test and Validate

```powershell
.\.venv\Scripts\python.exe -m pytest
node --check .\lan_transfer\static\user.js
node --check .\lan_transfer\static\admin.js
```

Tests cover authentication, lockout, account/group permissions, batch creation, visibility, search/sort, byte integrity, mtime, response headers, ZIP behavior, paths, duplicate names, transaction rollback, audit redaction, desktop lifecycle, logging, release metadata, and frontend contracts.

No dedicated lint or format command is declared. The two `node --check` commands are JavaScript syntax checks.

## Package a Windows Release

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\build_exe.ps1
```

The script installs dependencies, runs tests, and builds a windowed one-file executable with PyInstaller.

```text
dist\LANFileTransfer.exe
release-assets\LANFileTransfer.exe
release-assets\lan-file-transfer-v1.0.0-windows.zip
release-assets\SHA256SUMS.txt
```

No MSI is generated because there is no WiX, Inno Setup, or NSIS definition. Release binaries are not digitally signed; Windows may show an unknown-publisher warning. Download from the project Release page and verify `SHA256SUMS.txt`.

## Project Structure

| Path | Responsibility |
| --- | --- |
| `lan_transfer/desktop.py` | Tkinter window, QR codes, save-directory selection, and service lifecycle |
| `lan_transfer/server.py` | uvicorn thread startup, health, timeout, and shutdown |
| `lan_transfer/api.py` | FastAPI routes, role/session boundaries, visibility, sorting, downloads, and error mapping |
| `lan_transfer/auth.py` | Accounts, groups, PBKDF2 password hashes, sessions, IP lockout, and auth persistence |
| `lan_transfer/storage.py` | Streamed files, manifest, hash/mtime, ZIP, ownership, visibility, transactions, and tombstones |
| `lan_transfer/security.py` | Upload and stored-manifest path normalization/containment |
| `lan_transfer/audit.py` | Redacted JSONL audit trail |
| `lan_transfer/config.py` | Save directory, available port, LAN address, and URLs |
| `lan_transfer/static/` | Native user/admin browser applications |
| `tests/` | Backend, desktop, release, and frontend-contract regression suites |

## Security Notes

- Passwords are locally hashed with PBKDF2; session values and passwords must never be returned in JSON, validation errors, logs, or audit metadata.
- Five failed logins from one IP trigger a three-hour lockout.
- The service is HTTP on the LAN, not HTTPS. Network peers may be able to observe traffic; use only a trusted network.
- Guest-visible `public` filenames and files are intentionally reachable without sign-in.
- Raw download headers include integrity/cache/mtime metadata, but browsers control the final filesystem timestamp.
- Do not expose the listener through port forwarding, public Wi-Fi, a public firewall rule, or an untrusted VPN.

## Maintenance and Contributions

- Keep route policy in `api.py`, accounts and sessions in `auth.py`, file transactions in `storage.py`, and path validation in `security.py`; add focused regression coverage in the corresponding `tests/test_*.py` suite.
- Browser changes must preserve the separate user/admin contracts, Chinese/English strings, stale-response guards, and native no-CDN frontend. Run both `node --check` commands after editing JavaScript.
- Re-run permission, path, audit, rollback, and byte-integrity tests whenever a change crosses more than one backend module; a successful UI action alone does not prove the disk and audit state committed together.
- Dependency changes require an update to [the open-source audit](docs/OPEN_SOURCE_AUDIT.md). Release changes must rebuild, launch, inspect the portable archive, and verify metadata and checksums.
- Keep all three README versions aligned and retain the HTTP, trusted-LAN, default-password, public-file, mtime, and unsigned-binary warnings.

## Author

- HaoXiang Huang
- [Rays688888@Gmail.com](mailto:Rays688888@Gmail.com)
- <https://nextweb4.github.io/>
- <https://github.com/NextWeb4>

## License

[MIT](LICENSE) © 2026 HaoXiang Huang.