# Antivirus

> Soumettre un fichier au scan antivirus, suivre son statut et recevoir le résultat par webhook signé.

Le module antivirus analyse les fichiers que vos utilisateurs envoient, avant que votre application ne les accepte. L'analyse est **asynchrone** : vous soumettez le fichier, puis vous lisez son statut ou vous recevez le résultat sur votre propre URL.

Chaque scan consomme 1 [crédit](/v1.0/reference-api/credits) du client, débité à la soumission. L'appel doit porter un client et une application : utilisez le jeton d'un utilisateur de l'application ou une clé API liée à un client.

## Cycle de vie d'un scan

```mermaid
stateDiagram-v2
  [*] --> PENDING: POST /api/antivirus/scans
  PENDING --> SCANNING: prise en charge
  SCANNING --> CLEAN: aucune menace
  SCANNING --> INFECTED: menace détectée
  SCANNING --> ERROR: échec technique
  ERROR --> SCANNING: nouvelle tentative (3 au plus)
```

Un fichier déclaré `INFECTED` est placé en quarantaine. Un fichier identique, déjà déclaré infecté pour le même client et la même application, est déclaré infecté immédiatement.

## L'objet Scan

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant du scan |
| `status` | chaîne | `PENDING`, `SCANNING`, `CLEAN`, `INFECTED` ou `ERROR` |
| `filename` | chaîne | Nom d'origine du fichier |
| `fileSize` | entier | Taille en octets |
| `mimeType` | chaîne | Type déclaré à l'envoi |
| `fileHash` | chaîne (64) | Empreinte SHA-256, calculée pendant le scan |
| `priority` | entier, 1 à 10 | Priorité de traitement, 1 étant la plus haute (défaut 5) |
| `callbackUrl` | chaîne ou `null` | URL de rappel |
| `threatName` | chaîne ou `null` | Nom de la menace détectée |
| `threatSeverity` | chaîne ou `null` | `HIGH` pour un fichier infecté |
| `scanEngine`, `signatureVersion` | chaîne ou `null` | Moteur et version des signatures |
| `scanDurationMs` | entier ou `null` | Durée de l'analyse |
| `errorMessage` | chaîne ou `null` | Cause d'un statut `ERROR` |
| `queuedAt`, `startedAt`, `completedAt` | chaîne ISO 8601 ou `null` | Dates de mise en file, de début et de fin |

## Soumettre un fichier

::endpoint{method="POST" path="/api/antivirus/scans"}

**Droit requis** : `antivirus.scan`. Corps `multipart/form-data`.

| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `file` | fichier | oui | 100 Mo au plus | Fichier à analyser |
| `callbackUrl` | chaîne | non | HTTPS, adresse publique, 500 caractères au plus | URL qui recevra le résultat |
| `callbackSecret` | chaîne | non | 64 caractères au plus | Secret de signature du webhook. Obligatoire pour recevoir le webhook |
| `priority` | entier | non | 1 à 10 | Défaut 5 |

Si une politique de scan est définie pour votre client ou votre application, le fichier doit en respecter la taille maximale, les types MIME autorisés et les extensions bloquées. Le type est déterminé d'après le contenu du fichier, pas d'après son nom.

```bash
curl -s -X POST https://api.wakastart.app/api/antivirus/scans \
  -H "x-api-key: sk_test_exemple" \
  -F "file=@ordonnance.pdf" \
  -F "callbackUrl=https://api.mon-app.exemple.fr/webhooks/antivirus" \
  -F "callbackSecret=$ANTIVIRUS_WEBHOOK_SECRET"
```

```ts
const form = new FormData();
form.append("file", new Blob([buffer], { type: "application/pdf" }), "ordonnance.pdf");
form.append("callbackUrl", "https://api.mon-app.exemple.fr/webhooks/antivirus");
form.append("callbackSecret", process.env.ANTIVIRUS_WEBHOOK_SECRET!);

const res = await fetch("https://api.wakastart.app/api/antivirus/scans", {
  method: "POST",
  headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
  body: form,
});
const scan = await res.json(); // scan.status === "PENDING"
```

**Réponse `201`**

```json
{
  "id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
  "status": "PENDING",
  "filename": "ordonnance.pdf",
  "fileSize": 182344,
  "mimeType": "application/pdf",
  "priority": 5,
  "callbackUrl": "https://api.mon-app.exemple.fr/webhooks/antivirus",
  "queuedAt": "2026-10-23T09:20:00.000Z"
}
```

**Erreurs**

| Statut | Message | Cause |
|---|---|---|
| `400` | `Fichier requis` | Aucun fichier dans le champ `file` |
| `400` | `Antivirus service error` | Fichier refusé par la politique (taille, type, extension), secret trop long ou appel sans client ni application |
| `402` | `Antivirus service error` | Crédits insuffisants pour le client |
| `413` | `File too large` | Fichier de plus de 100 Mo |
| `503` | `Antivirus service error` ou `Antivirus service unavailable` | Service momentanément indisponible ; le scan n'est pas créé |

## Suivre le statut d'un scan

::endpoint{method="GET" path="/api/antivirus/scans/{id}/status"}

**Droit requis** : `antivirus.read`. Réponse légère, adaptée à une interrogation régulière.

```bash
curl -s https://api.wakastart.app/api/antivirus/scans/8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77/status \
  -H "x-api-key: sk_test_exemple"
```

**Réponse `200`**

```json
{ "id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77", "status": "CLEAN", "filename": "ordonnance.pdf", "completedAt": "2026-10-23T09:20:04.000Z" }
```

Interrogez toutes les quelques secondes, avec un délai croissant, jusqu'à un statut final : `CLEAN`, `INFECTED` ou `ERROR`.

## Lire le détail d'un scan

::endpoint{method="GET" path="/api/antivirus/scans/{id}"}

**Droit requis** : `antivirus.read`. Réponse : l'objet Scan complet, avec la menace détectée et l'empreinte du fichier. Le secret de rappel n'est jamais renvoyé.

**Erreurs** (pour les deux lectures) : `400` `Validation failed (uuid is expected)` ; `404` `Antivirus service error` si le scan n'existe pas ou appartient à un autre client.

## Recevoir le résultat par webhook

Si vous avez fourni `callbackUrl` **et** `callbackSecret`, Wakastart envoie le résultat à votre URL dès la fin du scan, pour les statuts `CLEAN` et `INFECTED`. Aucun webhook n'est envoyé pour `ERROR` : interrogez alors le statut.

Requête reçue :

```http
POST /webhooks/antivirus HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 5f2b1c…e9a0
X-Webhook-Timestamp: 2026-10-23T09:20:04.512Z

{
  "scanId": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
  "status": "CLEAN",
  "filename": "ordonnance.pdf",
  "fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "completedAt": "2026-10-23T09:20:04.000Z"
}
```

| Élément | Description |
|---|---|
| `X-Webhook-Signature` | HMAC-SHA256 du corps brut, avec votre `callbackSecret`, en hexadécimal |
| `X-Webhook-Timestamp` | Date d'envoi ; elle ne fait pas partie de la signature |
| `threatName` | Présent dans le corps quand `status` vaut `INFECTED` |

Vérifiez la signature sur le corps **brut**, avant tout traitement :

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function isValidAntivirusWebhook(rawBody: Buffer, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

Répondez `2xx` en moins de 10 secondes. En cas d'échec, Wakastart réessaie deux fois (après 1 puis 4 secondes). Traitez le webhook de façon idempotente en vous fondant sur `scanId`.
