Files
FileTransfer/README.md
T
DerSchandfleckandClaude Fable 5.2 278194b707 Dateitransfer: Server, Seiten, Tests und Docker-Dateien
Hochladen mit Upload-Code, kurzer Link zum Herunterladen, automatische
Löschung nach Ablauf der Frist. Node.js ohne zusätzliche Pakete.

- src/: HTTP-Server, Ablage auf der Platte, Zugriffsbegrenzung
- pages/, public/: Oberfläche in Deutsch und Englisch
- tools/: Transfers auflisten und löschen
- test/: 34 automatische Tests
- Dockerfile, compose.yaml: Betrieb als Container auf 127.0.0.1:8083

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-16 00:59:41 +01:00

161 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FileTransfer
Kleiner, privater Dateitransfer: Dateien hochladen, einen kurzen Link bekommen,
weitergeben – wer den Link kennt, kann die Dateien herunterladen. Nach Ablauf
der gewählten Frist löscht der Server sie von selbst.
- Hochladen nur mit **Upload-Code**, Herunterladen ohne Anmeldung über den Link
- Mehrere Dateien je Link, Frist wählbar (Vorgabe: 1, 7 oder 30 Tage)
- Große Dateien werden in Stücken übertragen; reißt die Verbindung ab, macht
der Browser an derselben Stelle weiter
- Oberfläche auf Deutsch und Englisch, hell oder dunkel je nach Gerät
- Keine Cookies, keine Analyse, nichts von fremden Servern
- Node.js ohne zusätzliche Pakete – es gibt nichts zu installieren und nichts zu bauen
## Lokal ausprobieren
Voraussetzung: Node.js ab Version 22.
```
cp .env.example .env
```
In der `.env` bei `UPLOAD_CODES` einen Code eintragen, dann:
```
npm start
```
Die Seite läuft danach unter http://localhost:8083. Mit `npm run dev` startet
der Dienst bei Änderungen am Code neu und liest Seiten und Skripte bei jedem
Aufruf frisch von der Platte.
## Einstellungen
Alle Einstellungen sind Umgebungsvariablen; liegt neben `server.js` eine Datei
`.env`, wird sie gelesen. Die vollständige Liste mit Erklärungen steht in
[.env.example](.env.example). Die wichtigsten:
| Variable | Vorgabe | Bedeutung |
|---------------------|--------------|---------------------------------------------------------|
| `UPLOAD_CODES` | leer | `name:code`, mehrere durch Komma getrennt. Leer = Hochladen gesperrt |
| `MAX_TRANSFER_SIZE` | `5GB` | größte Gesamtgröße eines Transfers |
| `STORAGE_QUOTA` | `50GB` | so viel dürfen alle Transfers zusammen belegen |
| `MIN_FREE_SPACE` | `5GB` | so viel muss auf der Platte frei bleiben |
| `EXPIRY_DAYS` | `1,7,30` | wählbare Fristen in Tagen |
| `SITE_NAME` | `shiuuji.de` | Name oben links auf der Seite |
| `TRUST_PROXY` | `0` | `1`, wenn ein Reverse-Proxy davorsteht |
Einen Upload-Code nimmst du zurück, indem du ihn aus `UPLOAD_CODES` löschst und
den Dienst neu startest. Bereits hochgeladene Dateien bleiben bis zu ihrer Frist.
## Betrieb auf dem Server (Docker)
Der Dienst läuft als Container und ist nur auf dem Server selbst unter
`127.0.0.1:8083` erreichbar. Nach außen gehört ein Reverse-Proxy mit HTTPS
davor (zum Beispiel Caddy), der Anfragen an diesen Port weiterreicht.
Einmalig einrichten, im Ordner des Repositorys:
1. Eigenen Benutzer für den Dienst anlegen und den Datenordner erstellen:
```
sudo useradd --system --no-create-home --shell /usr/sbin/nologin filetransfer
sudo install -d -o filetransfer -g filetransfer -m 700 data
```
2. `.env` aus der Vorlage erstellen und nur für root lesbar machen:
```
sudo cp .env.example .env
sudo chmod 600 .env
```
3. In der `.env` die Upload-Codes eintragen und am Ende zwei Zeilen mit den
Nummern des neuen Benutzers ergänzen (Ausgabe von `id filetransfer`):
```
APP_UID=<uid>
APP_GID=<gid>
```
4. Starten:
```
sudo docker compose up -d --build
```
Später:
| Zweck | Befehl |
|--------------------------------|-------------------------------------------------------------------|
| Status | `sudo docker compose ps` |
| Protokoll | `sudo docker compose logs --tail 50` |
| Neue Version einspielen | `sudo git pull && sudo docker compose up -d --build` |
| Node.js im Image aktualisieren | `sudo docker compose build --pull && sudo docker compose up -d` |
| Transfers auflisten | `sudo docker compose exec filetransfer node tools/transfers.js list` |
| Einen Transfer löschen | `sudo docker compose exec filetransfer node tools/transfers.js delete <kennung>` |
Die Kennung sind die zehn Zeichen hinter `/d/` im Link. Im Protokoll steht zu
jedem Transfer, mit welchem Upload-Code (Name) er angelegt wurde.
Hinweise für den Reverse-Proxy: Anfragen dürfen nicht zwischengespeichert
(gepuffert) werden und müssen Körper bis 8 MB durchlassen – so groß ist ein
Stück beim Hochladen. Caddy macht beides von Haus aus richtig.
## Wie es funktioniert
```
server.js Start: Einstellungen lesen, Dienst hochfahren
src/config.js Einstellungen aus Umgebungsvariablen
src/app.js HTTP-Server, Routen, Schutz-Header
src/store.js Ablage der Transfers auf der Platte, Aufräumen
src/limiter.js Zugriffsbegrenzung je Adresse
src/pages.js lädt pages/ und public/ in den Arbeitsspeicher
pages/ HTML-Seiten (beide Sprachen stehen im selben Dokument)
public/ Gestaltung und Skripte für den Browser
tools/transfers.js Auflisten und Löschen von der Kommandozeile
test/ automatische Tests (npm test)
```
Ein Transfer liegt unter `data/transfers/<kennung>/`: die Dateien nach Position
benannt (`0`, `1`, …) und daneben `meta.json` mit Namen, Größen und Frist. Die
Dateinamen der Nutzer werden nie als Pfad verwendet.
Ablauf eines Uploads:
1. `POST /api/transfers` mit Upload-Code und Dateiliste legt den Transfer an und
liefert ein Upload-Token und ein Lösch-Token.
2. `PUT /api/transfers/<kennung>/files/<nr>?offset=<n>` überträgt die Dateien in
Stücken von 8 MB. Der Server nimmt ein Stück nur an, wenn es genau an das
bisher Empfangene anschließt; deshalb lässt sich jedes Stück gefahrlos
wiederholen.
3. `POST /api/transfers/<kennung>/finish` schließt ab. Erst jetzt ist der Link
gültig und die Frist beginnt.
Das Lösch-Token merkt sich der Browser, damit man eigene Transfers auf der
Startseite unter „Zuletzt hochgeladen“ vorzeitig löschen kann.
## Sicherheit
- Upload-Codes werden zeitunabhängig verglichen; nach 10 falschen Versuchen ist
eine Adresse für 10 Minuten gesperrt. Auch das Durchprobieren von Links wird
gebremst.
- Kennungen sind 10 zufällige Zeichen (rund 8 × 10¹⁴ Möglichkeiten). Wer den
Link hat, hat Zugriff – Links also nur an die richtigen Leute geben.
- Hochgeladene Dateien werden ausschließlich als Download ausgeliefert
(`Content-Disposition: attachment`, `nosniff`, eigene Content-Security-Policy),
nie als Seite im Browser ausgeführt.
- Die Dateien liegen unverschlüsselt auf dem Server. Wer Zugriff auf den Server
hat, kann sie lesen.
- Im Protokoll stehen keine IP-Adressen und keine Dateinamen.
## Tests
```
npm test
```
Die Tests starten den Dienst mit einem eigenen, leeren Datenordner im
Temp-Verzeichnis und räumen ihn danach wieder weg.