À propos de ce cours
Objectifs de la leçon
- Servir un dossier de fichiers publics avec ServeStaticModule.
- Comprendre ce qui est exposé et ce qui ne doit jamais l'être.
- Distribuer un fichier privé avec StreamableFile après contrôle des droits.
- Choisir entre téléchargement et affichage avec Content-Disposition.
Un dossier public est servi tel quel ; un document privé passe par un contrôleur.
Fichiers publics : ServeStaticModule
npm install @nestjs/serve-static # NestJS 11 : @nestjs/serve-static@5
📄 src/app.module.ts
import { Module } from '@nestjs/common';
import { ServeStaticModule } from '@nestjs/serve-static';
import { join } from 'node:path';
import { DocumentsController } from './documents.controller';
@Module({
imports: [
// Fichiers publics : ./public servi sous /statique (logo, images des formations…)
ServeStaticModule.forRoot({
rootPath: join(process.cwd(), 'public'),
serveRoot: '/statique',
serveStaticOptions: { maxAge: '7d', index: false, fallthrough: false },
}),
],
controllers: [DocumentsController],
})
export class AppModule {}
rootPath: le dossier sur le disque.process.cwd()est le dossier du projet, d'où l'on lancenpm run start.serveRoot: le préfixe d'URL.public/logo.pngdevient/statique/logo.png. Le préfixe globalapine s'applique pas.serveStaticOptions: options d'Express (serve-static).maxAgeautorise le navigateur à garder le fichier 7 jours ;index: falsedésactiveindex.html;fallthrough: falserépond directement 404 pour un fichier absent.
Fichiers privés : un contrôleur et StreamableFile
📄 src/documents.controller.ts
import { Controller, ForbiddenException, Get, Headers, NotFoundException, Param, ParseUUIDPipe, StreamableFile } from '@nestjs/common';
import { createReadStream, existsSync, statSync } from 'node:fs';
import { join } from 'node:path';
// Documents privés : stockés HORS de public/, distribués par un contrôleur qui vérifie les droits
const DOCUMENTS = new Map([
['6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f', { proprietaire: 'sami', nom: 'attestation de stage.pdf', type: 'application/pdf' }],
]);
@Controller('documents')
export class DocumentsController {
@Get(':id')
telecharger(@Param('id', ParseUUIDPipe) id: string, @Headers('x-utilisateur') moi?: string): StreamableFile {
return this.fichier(id, moi, 'attachment'); // « Enregistrer sous… »
}
@Get(':id/apercu')
apercu(@Param('id', ParseUUIDPipe) id: string, @Headers('x-utilisateur') moi?: string): StreamableFile {
return this.fichier(id, moi, 'inline'); // affiché dans le navigateur
}
private fichier(id: string, moi: string | undefined, mode: 'attachment' | 'inline') {
const doc = DOCUMENTS.get(id);
if (!doc) throw new NotFoundException('Document introuvable');
if (doc.proprietaire !== moi) throw new ForbiddenException('Ce document ne vous appartient pas');
const chemin = join(process.cwd(), 'stockage', id + '.pdf');
if (!existsSync(chemin)) throw new NotFoundException('Fichier absent du stockage');
return new StreamableFile(createReadStream(chemin), {
type: doc.type,
length: statSync(chemin).size,
// filename : nom simple (ancien navigateurs) ; filename* : nom exact, accents et espaces compris (RFC 6266)
disposition: `${mode}; filename="document.pdf"; filename*=UTF-8''${encodeURIComponent(doc.nom)}`,
});
}
}
- Les documents sont dans
stockage/, en dehors du dossier servi : aucune URL directe n'y mène. - Le contrôleur vérifie les droits (ici un simple en-tête ; dans le TP 9, le jeton et le rôle), puis renvoie
new StreamableFile(flux): le fichier est lu et envoyé par morceaux, sans être chargé entièrement en mémoire. Content-Disposition:attachmentdéclenche le téléchargement,inlinel'affichage dans le navigateur (aperçu d'un PDF).filename*=UTF-8''…transmet le nom d'origine avec ses espaces et accents (RFC 6266) ;filename="…"sert de solution de repli.
Résultat réellement obtenu :
— Fichiers publics (ServeStaticModule)
GET /statique/logo.png → 200 <216 octets binaires> [content-type: image/png] [content-length: 216] [cache-control: public, max-age=604800] [content-disposition: null]
GET /statique/css/site.css → 200 body { margin: 0 } [content-type: text/css; charset=utf-8] [cache-control: public, max-age=604800]
GET /statique/absent.png → 404 {"message":"Cannot GET /statique/absent.png","error":"Not Found","statusCode":404}
GET /statique/ → 404 {"statusCode":404,"message":"Not Found"}
GET /statique/..%2f..%2fstockage%2f6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f.pdf → 403 {"statusCode":403,"message":"Forbidden"}
— L'API n'est pas affectée
GET /api/documents/pas-un-uuid → 400 {"message":"Validation failed (uuid is expected)","error":"Bad Request","statusCode":400}
— Fichiers privés (contrôleur + StreamableFile)
GET /api/documents/6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f → 403 {"message":"Ce document ne vous appartient pas","error":"Forbidden","statusCode":403}
GET /api/documents/6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f → 403 {"message":"Ce document ne vous appartient pas","error":"Forbidden","statusCode":403}
GET /api/documents/6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f → 200 <209 octets binaires> [content-type: application/pdf] [content-length: 209] [cache-control: null] [content-disposition: attachment; filename="document.pdf"; filename*=UTF-8''attestation%20de%20stage.pdf]
GET /api/documents/6f1c2a9e-4b7d-4e2a-9c3f-1a2b3c4d5e6f/apercu → 200 <209 octets binaires> [content-type: application/pdf] [content-disposition: inline; filename="document.pdf"; filename*=UTF-8''attestation%20de%20stage.pdf]
Lecture
- Le logo et la feuille de style sont servis avec le bon type et
Cache-Control: public, max-age=604800(7 jours). - Fichier absent ou dossier sans index : 404.
- La tentative de remonter dans l'arborescence (
..%2f..%2fstockage%2f…, soit../../stockage/…encodé) est refusée (403) parserve-static. - Le document privé : 403 sans utilisateur ou pour Ines, 200 pour Sami avec la taille, le type et le nom d'origine.
Variante : useStaticAssets d'Express
Sans module supplémentaire, une application Express peut servir un dossier directement depuis main.ts:
📄 src/main.ts (extrait)
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.setGlobalPrefix('api');
app.useStaticAssets(join(process.cwd(), 'public'), { prefix: '/statique/', maxAge: 3600 * 1000 });
Résultat réellement obtenu :
GET /statique/logo.png → 200 <216 octets binaires> [content-type: image/png] [cache-control: public, max-age=3600]
GET /api/statique/logo.png → 404 {"message":"Cannot GET /api/statique/logo.png","error":"Not Found","statusCode":404}
Le résultat est le même. ServeStaticModule se configure dans un module (donc avec ConfigService, et il fonctionne aussi avec Fastify) ; useStaticAssets est plus direct mais propre à Express.
En production, les fichiers publics sont souvent servis par le serveur web placé devant Node.js (nginx), ou par un CDN, plus efficaces pour cette tâche (chapitre 20). Les documents privés, eux, passent toujours par l'API qui contrôle les droits. Et rappelez-vous : un fichier placé dans le dossier public est accessible à tout le monde, sans authentification.
Activités
Activité 1 Les images des formations
Servez public/formations/ sous /images avec un cache d'un jour. Ajoutez à chaque formation renvoyée par l'API un champ image contenant l'URL complète (http://localhost:3000/images/web.jpg), construite à partir d'une variable URL_PUBLIQUE du .env.
Voir le corrigé
ServeStaticModule.forRoot({
rootPath: join(process.cwd(), 'public', 'formations'),
serveRoot: '/images',
serveStaticOptions: { maxAge: '1d', index: false },
}),
// dans le service
const base = this.config.get('URL_PUBLIQUE', 'http://localhost:3000');
return formations.map((f) => ({ ...f, image: f.image ? `${base}/images/${f.image}` : null }));
L'URL publique vient de la configuration : en production, elle deviendra https://api.mondomaine.tn sans modifier le code.
Activité 2 Que voit le visiteur ?
Un collègue configure ServeStaticModule.forRoot({ rootPath: process.cwd() }) « pour servir le dossier public ». Que peut télécharger un visiteur ? Corrigez.
Voir le corrigé
Tout le projet : /.env (mots de passe, secret JWT), /package.json, /src/…, /stockage/… (les documents des utilisateurs). C'est une faille grave. Correction : rootPath: join(process.cwd(), 'public'), un dossier qui ne contient que des fichiers destinés au public, et un serveRoot explicite.
Activité 3 Aperçu ou téléchargement
Modifiez GET /api/documents/:id pour accepter ?mode=apercu (affichage) ou rien (téléchargement), avec un ParseEnumPipe facultatif. Testez dans le navigateur avec un vrai PDF.
Voir le corrigé
@Get(':id')
telecharger(
@Param('id', ParseUUIDPipe) id: string,
@Query('mode', new ParseEnumPipe(['apercu', 'telechargement'], { optional: true })) mode = 'telechargement',
@Headers('x-utilisateur') moi?: string,
) {
return this.fichier(id, moi, mode === 'apercu' ? 'inline' : 'attachment');
}
Activité 4 Un nom de fichier piégé
Un document a pour nom d'origine rapport";.pdf. Que se passerait-il si on écrivait filename="${doc.nom}" sans encodage dans Content-Disposition? Pourquoi la leçon utilise-t-elle filename*=UTF-8''${encodeURIComponent(nom)}?
Voir le corrigé
Le guillemet fermerait la valeur et le reste serait interprété comme d'autres paramètres de l'en-tête : nom tronqué, voire en-tête invalide (et, avec un retour à la ligne, une tentative d'injection d'en-têtes, que Node.js refuse). encodeURIComponent encode tous les caractères spéciaux, et filename* est la forme prévue par la RFC 6266 pour les noms non ASCII.
À retenir
- ServeStaticModule.forRoot({ rootPath, serveRoot, serveStaticOptions }) ou app.useStaticAssets() : fichiers publics.
- Tout ce qui est dans le dossier servi est public : jamais de .env, de sources ni de documents d'utilisateurs.
- Documents privés : hors du dossier public, contrôleur avec contrôle des droits, StreamableFile.
- Content-Disposition : attachment (télécharger) ou inline (afficher) ; filename* pour les accents.
- Cache navigateur (maxAge) pour les fichiers publics ; en production, souvent nginx ou un CDN.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !