Suggestion: Add a module for temporary hashed Signature File Downloads

[lucas-amiaud]

Description

Add a new module to support secure, time-limited file downloads using hashed signatures.

This would be useful in scenarios where files should be accessible only via temporary URLs, without exposing internal paths or requiring user authentication on every request.

Suggested features

• Generate a signed URL with:
  • A file identifier
  • An expiration timestamp
  • A hashed signature (e.g., HMAC with a secret key)
• Endpoint to verify the signature and expiration before serving the file
• Optional support for one-time download or download count limits

Benefits

• Improved security for file sharing
• Easy integration into systems requiring temporary public links
• Keeps the core lightweight while offering powerful extensibility

[amanteaux]

We would also need to make sure that using the "base" endpoint, it is not possible to recover the file using its identifier. It is important in projects where the two endpoints will coexist.

So the identifier used in the temporary share must be independent of the real file identifier.

[lucas-amiaud]

Spécification technique - Module de liens signés pour Plume File

1. Résumé du besoin

Le but de ce module est de permettre un accès sécurisé aux fichiers gérés par la librairie Plume File via des URLs signées.
Ces URLs incluent l'identifiant du fichier, une date d’expiration et une signature cryptographique.
L’accès au fichier est possible uniquement via un webservice qui valide cette signature et contrôle les conditions d’accès.
La génération de ces URLs se fera directement dans le code backend, via un service dédié.

2. Objectifs

• Fournir un service Java (SignedFileUrlService) qui implémente FileUrlService et permet :
  • De générer des URLs signées incluant : identifiant du fichier (uniqueName), date d’expiration (expiresAt), signature hashée (signature).
  • De configurer des options comme :
    • Téléchargement one-shot (URL invalide après premier accès)
    • Limitation par nombre de téléchargements
• Fournir un endpoint de téléchargement sécurisé qui valide la signature.
• Empêcher tout accès direct au fichier en dehors du webservice validateur.

3. Schéma d’architecture

[Code backend]
   |
   | SignedFileUrlService.generateUrl(uniqueName, expiresAt, options)
   v
[URL signée] --> [Client]
   |
   v
[Endpoint de téléchargement sécurisé] --(Validation signature & expiration)--> [Service de fichiers]
   |
   v
[Fichier retourné ou accès refusé]

4. SignedFileUrlService

4.1 Interface et responsabilités

Le service SignedFileUrlService :

• Implémente l’interface FileUrlService de Plume File.
• Génère une URL sécurisée à partir :
  • d’un identifiant de fichier (uniqueName)
  • d’une date d’expiration (expiresAt)
  • d’options de sécurité (oneShot, maxDownloads)
• Utilise une clé secrète configurée côté serveur.
• Produit une URL contenant les paramètres et la signature.

4.2 Signature

• Algorithme recommandé : HMAC-SHA256
• Formule :

signature = Base64( HMAC-SHA256(secretKey, uniqueName + expiresAt) )

• La signature est ajoutée en paramètre de l’URL.

5. Endpoint - Téléchargement avec validation

Méthode : GET
URL : /files/{uniqueName}

Grâce à cette signature, nous sommes sûr de ne pas cohabiter avec le FileWs de plume-file-web-download-jersey

Paramètres (path) :

• uniqueName (string, requis)

Paramètres (query) :

• expiresAt (timestamp, requis)
• signature (string, requis)

Réponses :

• 200 OK : fichier retourné
• 403 Forbidden : signature invalide, URL expirée ou quota dépassé
• 410 Gone : URL one-shot déjà utilisée

5.1 Validation côté serveur

1. Vérifier que expiresAt est dans le futur
2. Recalculer la signature avec les mêmes paramètres
3. Comparer avec la signature reçue
4. Vérifier quotas ou statut one-shot
5. Servir le fichier uniquement si toutes les conditions sont remplies

6. Gestion des options

6.1 One-shot

• Stocker en base l’état "utilisé"
• Après premier accès, invalider l’entrée

6.2 Limitation par compteur

• Incrémenter un compteur à chaque téléchargement
• Refuser si dépassement du quota

7. Gestion des erreurs

Code HTTP	Signification
200	Fichier retourné
403	Accès refusé (signature invalide, quota dépassé)
410	URL expirée ou one-shot déjà utilisé

8. Recommandations de sécurité

• Ne jamais exposer l’URL directe de stockage du fichier
• Utiliser HTTPS pour toutes les communications
• Clé secrète forte et régénérable
• Limiter la durée de vie des URLs signées (ex : max 1h)
• Enregistrer les tentatives invalides pour détection d’abus

---