Analyse antivirus

Chaque fichier téléversé dans un transfert Coffrify passe par une analyse antivirus avant d'être mis à disposition des destinataires. Cette page explique comment suivre l'état de l'analyse grâce au champ scan_status, comment recevoir les résultats en temps réel via les webhooks, et comment réagir lorsqu'un fichier est détecté comme infecté. L'analyse fonctionne aussi bien en mode serveur (AES-256-GCM) qu'en mode de bout en bout, sans que vous ayez à modifier votre intégration.

Le cycle de vie d'une analyse

À la création d'un transfert, les fichiers sont d'abord en attente d'analyse. Coffrify les inspecte de façon asynchrone : l'analyse peut se terminer en quelques secondes pour un petit document, ou prendre plus longtemps pour des fichiers volumineux. Vous pouvez interroger l'état à tout moment, mais la méthode recommandée reste l'abonnement aux webhooks décrits plus bas, qui vous notifient dès que le verdict est rendu.

Tant qu'un fichier n'a pas été déclaré sain, considérez sa diffusion comme suspendue : c'est votre application qui décide quoi montrer au destinataire pendant cette fenêtre.

Le champ scan_status

L'objet transfer renvoyé par l'API expose un champ scan_status qui reflète l'état global de l'analyse pour le transfert. Vous le retrouvez dans la réponse de POST /v1/transfers ainsi que dans GET /v1/transfers/{id}.

Lire scan_status à la création

À la création, le transfert est presque toujours en pending ou scanning, car l'analyse est asynchrone. Ne vous fiez donc pas à la valeur initiale pour autoriser un téléchargement : attendez le verdict via un webhook ou un appel GET ultérieur.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const { transfer } = await coffrify.transfers.create({
  files: [{ name: 'contrat.pdf', size: 482190, mime_type: 'application/pdf' }],
  transfer_title: 'Contrat de prestation'
});
 
console.log(transfer.id, transfer.scan_status);
// trf_... pending

Les évènements webhook d'analyse

Plutôt que d'interroger l'API en boucle, abonnez un endpoint webhook aux évènements d'analyse. Coffrify vous notifie dès que le verdict est disponible. Trois évènements concernent directement l'antivirus.

L'évènement transfer.scanned est un signal générique de fin d'analyse : il est pratique pour journaliser ou déclencher une vérification. Les évènements transfer.scan_clean et transfer.scan_infected portent directement le verdict, ce qui vous permet de réagir sans relire l'état. Vous pouvez vous abonner à l'un, à l'autre, ou aux trois selon votre logique.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
await coffrify.webhooks.create({
  url: 'https://exemple.com/coffrify/webhooks',
  events: [
    'transfer.scan_clean',
    'transfer.scan_infected'
  ]
});

Réagir à un verdict

La règle est simple : n'exposez le lien de partage à un destinataire qu'après réception de transfer.scan_clean (ou lorsque scan_status vaut clean). À l'inverse, lorsque vous recevez transfer.scan_infected, coupez immédiatement la diffusion. Selon votre besoin, vous pouvez masquer le lien dans votre interface, alerter l'expéditeur, puis supprimer le transfert côté Coffrify pour qu'il ne soit plus accessible du tout.

// Endpoint webhook (Express)
import express from 'express';
import { Coffrify } from '@coffrify/sdk';
 
const app = express();
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
app.post('/coffrify/webhooks', express.json(), async (req, res) => {
  const { type, data } = req.body;
 
  if (type === 'transfer.scan_clean') {
    // Le fichier est sain : on peut révéler le lien au destinataire
    await publierLienAuDestinataire(data.transfer.id, data.transfer.share_url);
  }
 
  if (type === 'transfer.scan_infected') {
    // Menace détectée : on coupe la diffusion et on supprime le transfert
    await masquerLienDansLInterface(data.transfer.id);
    await coffrify.transfers.delete(data.transfer.id);
    await alerterExpediteur(data.transfer.id);
  }
 
  res.sendStatus(200);
});

En résumé

• Le champ scan_status passe de pending ou scanning à clean ou infected.
• N'autorisez le téléchargement qu'une fois le verdict clean confirmé.
• Abonnez un webhook à transfer.scan_clean et transfer.scan_infected plutôt que d'interroger l'API en boucle.
• Sur transfer.scan_infected, masquez le lien puis supprimez le transfert via DELETE /v1/transfers/{id}.
• L'analyse fonctionne en mode serveur comme en mode de bout en bout.