Files
upandown/README.md
T
claude BotandClaude Opus 5.5 e79a813272 Lot 3 (4/5) : API admin S3, variables S3_*, tests et documentation
GET/PUT /api/admin/s3 et POST /api/admin/s3/test (administrateurs) ;
S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY (_FILE),
S3_INSECURE ; miniatures S3 sous DATA_DIR/.s3cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LNfwm4pfYR9C914C2EeiuB
2026-11-20 18:05:17 +01:00

95 lines
8.0 KiB
Markdown

# Up And Down
Dépôt et téléchargement de fichiers **auto-hébergé**, avec un navigateur de fichiers complet. Même modèle qu'[Excalicloud](https://github.com/vLab-BZH/excalicloud) (explorateur, espaces personnels, favoris, tags, corbeille, partage, authentification OIDC ou locale), mais pour des fichiers **de tout type**.
- **Envoi** : glisser-déposer de fichiers et de dossiers entiers, envoi en flux (pas de limite de mémoire), plusieurs fichiers en parallèle, progression, annulation, nouvel essai, choix « garder les deux / remplacer / ignorer », date de modification d'origine conservée.
- **Navigation** : 4 affichages (liste, tableau triable, vignettes, galerie), recherche (noms, tags, **contenu des fichiers texte**), tags, favoris (fichiers et dossiers), sélection multiple, glisser-déposer pour déplacer, miniatures d'images (EXIF pris en compte).
- **Aperçu intégré** : images, vidéo, audio, PDF, texte, CSV (tableau paginé), Markdown et code colorisé (le HTML s'affiche comme du code, jamais rendu), avec navigation ←/→ dans le dossier.
- **Téléchargement** : fichier (reprise possible, `Range`) ou dossier / sélection en **ZIP** généré en flux.
- **Espaces** : arborescence commune + espace **Personnel** privé par utilisateur ; poubelle ; historique des versions (chaque remplacement garde l'ancien contenu, restauration en un clic).
- **Partage** par lien (`/s/<jeton>`) d'un fichier ou d'un dossier : durée au choix, **mot de passe** facultatif, compteur de téléchargements, révocation, sans compte pour le destinataire.
- **Comptes** : comptes locaux avec **inscription** (fermée, avec validation, ou libre), **connexion OIDC** (Authentik, Keycloak...), ou les deux. Rôles administrateur / utilisateur, quotas, jetons d'API.
- **Sécurité** : conteneur non-root en lecture seule, un seul binaire Go (bibliothèque standard, aucune dépendance), fichiers servis sans jamais exécuter leur contenu dans l'origine de l'application.
## Démarrage
```bash
cp .env.example .env # optionnel
docker compose up -d --build
# http://localhost:8080 : le premier compte créé devient l'administrateur
```
Pour imposer l'administrateur : `ADMIN_USER` et `ADMIN_PASSWORD` dans `.env`. Les fichiers sont de simples fichiers sur le volume `./data` (`chown -R 65532:65532 ./data` pour un bind mount).
## Authentification
| `AUTH_MODE` | Comportement |
|---|---|
| `local` (défaut) | Comptes locaux (mot de passe PBKDF2-SHA256), inscription selon `REGISTRATION` |
| `oidc` | Connexion uniquement via le fournisseur OIDC |
| `both` | Formulaire local **et** bouton OIDC |
| `none` | Aucune authentification intégrée (reverse proxy qui authentifie) ; un seul utilisateur, tout le monde administre |
**Inscription** (`REGISTRATION`, modifiable ensuite dans *Administration > Général*) : `closed` (l'administrateur crée les comptes), `approval` (les inscrits attendent la validation d'un administrateur), `open`. Tant qu'aucun administrateur n'existe, le premier compte créé (inscription ou première connexion OIDC) le devient.
**OIDC** : `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (vide : client public, PKCE seul), URI de redirection `https://<hôte>/auth/callback` (ou `OIDC_REDIRECT_URL`). `OIDC_ALLOWED_GROUPS` restreint l'accès ; `OIDC_ADMIN_GROUPS` / `OIDC_ADMIN_EMAILS` désignent les administrateurs (synchronisés à chaque connexion). Les comptes OIDC sont créés à la première connexion ; un e-mail identique d'un autre sujet ne fusionne jamais deux comptes.
## Variables
| Variable | Défaut | Rôle |
|---|---|---|
| `LISTEN_ADDR` / `DATA_DIR` | `:8080` / `/data` | Écoute et volume |
| `MAX_UPLOAD_MB` | `0` | Taille max d'un fichier (0 : illimité) |
| `USER_QUOTA_MB` | `0` | Quota de l'espace personnel (0 : illimité) |
| `COMMON_READONLY` | `false` | Commun en lecture seule pour les non-administrateurs |
| `TRASH_DAYS` | `0` | Purge de la poubelle (0 : jamais) |
| `HISTORY_KEEP` / `HISTORY_INTERVAL` / `HISTORY_MAX_AGE` | `10` / `0` / `0` | Versions gardées par fichier, écart minimal, âge maximal |
| `SESSION_TTL` / `SESSION_SECRET` | `24h` / aléatoire | Session ; clé de signature (sinon `DATA_DIR/.session-secret`). Obligatoire avec `DATABASE_URL` ; `hex:<contenu de .session-secret>` garde les sessions ouvertes |
| `SHARE_SECRET` | aléatoire | Clé de signature des liens de partage. Obligatoire avec `DATABASE_URL` ; `hex:<contenu de .share-secret>` garde valides les liens existants |
| `PUBLIC_URL` | | URL publique (cookies `Secure`) |
| `S3_ENDPOINT` / `S3_REGION` / `S3_BUCKET` | / `garage` / | Racine S3 (Garage ou S3 compatible), exige `DATABASE_URL`. Configurable aussi dans Administration ; une variable définie verrouille son champ |
| `S3_ACCESS_KEY` / `S3_SECRET_KEY` (ou `_FILE`) / `S3_INSECURE` | / / `false` | Clés du bucket ; `S3_INSECURE=true` : HTTP pour un endpoint sans schéma. Clé saisie dans l'interface : chiffrée en base avec `SHARE_SECRET`, jamais renvoyée |
Les valeurs d'inscription, de quota, de lecture seule et de poubelle sont des défauts : une fois modifiées dans l'interface, c'est le réglage de l'interface qui prime.
Racine S3 : dossier « S3 » commun à tous, mêmes droits que l'arborescence commune (lecture seule possible, l'administrateur écrit toujours). Le bucket doit être vide au départ ; l'arborescence vit dans le catalogue PostgreSQL et chaque fichier garde la clé d'objet fixée au dépôt (renommer ou déplacer ne touche pas le bucket). Pas d'historique de versions, de recherche plein texte ni de favoris sur S3. Une configuration modifiée dans l'interface est reprise par toutes les instances sous 30 s. Les variables `S3_*` doivent être ajoutées au bloc `environment` du service dans `docker-compose.yml` si on les utilise.
## API et jetons
Chaque utilisateur peut créer des jetons (*Jetons d'API*) pour scripter :
```bash
curl -T rapport.pdf -H "Authorization: Bearer upd_..." \
"https://cloud.example.org/api/file?path=.perso/rapport.pdf&conflict=overwrite"
curl -OJ -H "Authorization: Bearer upd_..." "https://cloud.example.org/api/file?path=.perso/rapport.pdf"
```
Les routes sont décrites en tête de [`internal/api/api.go`](internal/api/api.go). `.perso/...` est l'espace personnel, `.favoris` les favoris, `.poubelle` la poubelle.
## Sécurité : ce qui est fait
- Un fichier déposé ne s'exécute jamais dans l'application : seuls les types sûrs (images, vidéo, audio, PDF, texte) s'affichent en ligne ; HTML, SVG hors `<img>`, scripts et inconnus sont téléchargés (`attachment`), le texte est servi en `text/plain`, et un SVG ouvert directement l'est sous un CSP `sandbox`.
- Chemins normalisés sous la racine, noms cachés (`.trash`, `.accounts.json`...) refusés, liens symboliques ignorés ou refusés.
- Sessions invalidées dès qu'un compte est désactivé ou supprimé ; limitation des tentatives de connexion, d'inscription et de déverrouillage de lien ; en-tête `Origin` contrôlé sur les requêtes modifiantes ; jeton d'un lien absent des journaux.
- Jetons et mots de passe de liens conservés hachés ; liens non énumérables (id 128 bits signé HMAC).
- Suppression d'un compte : son espace personnel est mis de côté (`.users-removed`), jamais hérité par un homonyme.
À faire par l'exploitant : TLS devant le service (Traefik, Caddy, nginx), purge de `.trash` / `.users-removed`, sauvegarde du volume.
## Développement
```bash
go test ./... # backend (sans ouvrir de port)
cd frontend && npm install && npm run build # construit web/dist, embarqué dans le binaire
go run ./cmd/server # http://localhost:8080 (DATA_DIR=./data)
cd frontend && npm run dev # rechargement à chaud, proxy vers :8080
```
## Évolutions possibles
Envoi par morceaux (reprise après coupure, proxys à limite de corps), liens de dépôt (envoi seul), WebDAV, miniatures vidéo/PDF/WebP, recherche dans les PDF et documents Office, 2FA.
## Licence
MIT, voir [`LICENSE`](LICENSE). Une partie du code (authentification OIDC, explorateur, icônes Papicons) est reprise d'Excalicloud, voir [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).