# Référence du module HDS

> Authentification, permissions par rôle, objets, statuts, opérations, erreurs et limites du module de données de santé.

Toutes les opérations passent par l'API publique, sous le préfixe `https://api.wakastart.app/api/hds`. Les endpoints sont aussi décrits dans la [référence API — HDS](/v1.0/reference-api/hds).

## Authentification

| Élément | Valeur |
|---|---|
| En-tête | `Authorization: Bearer <jeton d'accès Keycloak de l'utilisateur, émis pour l'application>` |
| Rôle minimal | au moins un rôle HDS ; sinon `403` |
| Clés API `sk_…` | non acceptées : elles ne portent pas de rôle HDS |
| Espace | celui du client de l'utilisateur, déduit du jeton |
| Format des corps | JSON, ou `multipart/form-data` pour les fichiers |

## Permissions par rôle

| Opération | ADMIN | HEALTHCARE | MEDICAL | PATIENT | STORAGE | DELETE |
|---|:-:|:-:|:-:|:-:|:-:|:-:|
| Lire coffres, documents, dossiers | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Créer un coffre | ✓ | ✓ | | | ✓ | |
| Modifier un coffre (propriétaire) | ✓ | | | | | |
| Supprimer un coffre (propriétaire) | ✓ | | | | | ✓ |
| Exporter un coffre | ✓ | | | ✓ | | |
| Déposer un document | ✓ | ✓ | | ✓ | ✓ | |
| Supprimer un document | ✓ | | | | | ✓ |
| Créer, renommer un dossier, y ranger un document | ✓ | ✓ | | | ✓ | |
| Supprimer un dossier | ✓ | | | | | ✓ |
| Lire les partages | ✓ | ✓ | | | ✓ | |
| Créer un partage | ✓ | ✓ | | | | |
| Révoquer un partage (auteur) | ✓ | | | | | ✓ |
| Lire les consentements | ✓ | ✓ | ✓ | ✓ | | |
| Enregistrer un consentement | ✓ | ✓ | | | | |
| Activer un accès d'urgence | ✓ | ✓ | | | | |
| Lire, révoquer les accès d'urgence | ✓ | | | | | |
| Journal d'audit, intégrité, rapports, revues, alertes, sauvegardes, espace | ✓ | | | | | |

En plus du rôle, toute opération sur un coffre exige d'en être propriétaire ou destinataire d'un partage actif.

## Objets

### Espace

| Champ | Description |
|---|---|
| `networkWid` | WID du client. |
| `status` | `PROVISIONING`, `ACTIVE`, `DECOMMISSIONING`, `DECOMMISSIONED`. |
| `storageQuotaBytes` | Quota de stockage, 10 737 418 240 (10 Go) par défaut. |
| `maxVaults` | Nombre maximal de coffres, 1 000 par défaut. |
| `maxDocuments` | Nombre maximal de documents, 50 000 par défaut. |
| `provisionedAt` | Date d'activation. |

### Coffre

| Champ | Description |
|---|---|
| `vaultId` | Identifiant `vlt_…`. |
| `type` | `PATIENT`, `STRUCTURAL`, `RESEARCH`, `TEMPORARY`. |
| `status` | `ACTIVE`, `ARCHIVED`, `SUSPENDED`, `DELETED`. |
| `label` | Libellé, 255 caractères au plus. |
| `ownerId` | Identifiant Keycloak du propriétaire. |
| `ownerTeamId` | Équipe propriétaire (`STRUCTURAL`). |
| `patient` | `externalId`, `ins`, `firstName`, `lastName`, `birthDate` (`PATIENT`). |
| `pseudonymizedPatientId` | Référence pseudonymisée, ou `null`. |
| `metadata` | Paires clé-valeur libres. |
| `storageUsedBytes`, `documentCount` | Volume et nombre de documents du coffre. |
| `retentionPolicy` | `STANDARD`, `EXTENDED`, `LEGAL_HOLD`, `CUSTOM`. |
| `expiresAt` | Date de fin (`TEMPORARY`), ou `null`. |
| `createdAt`, `updatedAt` | Dates. |

### Document

| Champ | Description |
|---|---|
| `docId` | Identifiant `doc_…`. |
| `vaultId`, `folderId` | Coffre et dossier (`null` à la racine). |
| `originalFilename`, `mimeType`, `sizeBytes` | Nom, type et taille du fichier d'origine. |
| `status` | Voir [statuts d'un document](#statuts-dun-document). |
| `currentVersion` | Numéro de la version courante. |
| `versions` | Historique : `version`, `sizeBytes`, `uploadedAt`, `uploadedBy`, `comment` (et `hashSha256` dans l'historique dédié). |
| `hashSha256` | Empreinte SHA-256 du fichier d'origine (détail). |
| `antivirusStatus` | Résultat du contrôle antivirus au dépôt. |
| `tags`, `medicalMetadata`, `customMetadata` | Métadonnées. |
| `uploadedBy` | Identifiant Keycloak de l'auteur du dépôt. |
| `legalHold` | `true` si le document est sous conservation légale. |
| `deduplicated` | `true` si le dépôt a renvoyé un document existant (réponse de dépôt uniquement). |

### Dossier

| Champ | Description |
|---|---|
| `folderId` | Identifiant `fld_…`. |
| `vaultId`, `parentFolderId` | Coffre et dossier parent (`null` à la racine). |
| `name`, `sortOrder` | Nom (255 caractères) et ordre d'affichage. |
| `createdBy`, `createdAt`, `updatedAt` | Auteur et dates. |

### Partage

| Champ | Description |
|---|---|
| `shareId` | Identifiant `shr_…`. |
| `vaultId` | Coffre partagé. |
| `targetUserId` | Identifiant Keycloak du destinataire. |
| `level` | `READ`, `READ_WRITE`, `FULL_CONTROL`. |
| `grantedBy` | Auteur du partage ; `BREAK_GLASS_SYSTEM` pour un accès d'urgence. |
| `active` | `false` après révocation. |
| `revokedAt`, `revokedBy` | Révocation. |

### Consentement

| Champ | Description |
|---|---|
| `consentId` | Identifiant `cst_…`. |
| `vaultId`, `patientId` | Coffre et patient. |
| `purpose`, `scope`, `scopeDetail` | Finalité et périmètre. |
| `collectionMethod`, `collectedAt`, `collectedBy` | Recueil. |
| `status` | `ACTIVE`, `WITHDRAWN`, `EXPIRED`. |
| `expiresAt` | Fin de validité convenue, ou `null`. |
| `withdrawnAt`, `withdrawnBy`, `withdrawalConsequence` | Retrait. |

### Accès d'urgence

| Champ | Description |
|---|---|
| `breakGlassId` | Identifiant `bg_…`. |
| `vaultId`, `shareId` | Coffre ouvert et partage créé. |
| `requestedBy`, `requestedByEmail`, `justification` | Demandeur et justification. |
| `status` | `ACTIVE`, `EXPIRED`, `REVOKED`, `PENDING_REVIEW`. |
| `grantedAt`, `expiresAt` | Activation, et date indicative fixée 24 h plus tard. L'accès prend fin à sa révocation. |
| `revokedAt`, `revokedBy` | Révocation. |

### Entrée du journal d'audit

| Champ | Description |
|---|---|
| `auditId`, `timestamp` | Identifiant `aud_…` et horodatage. |
| `userId`, `sourceIp`, `userAgent`, `correlationId` | Origine. |
| `eventType`, `eventCategory`, `action` | Nature de l'événement. |
| `resourceType`, `resourceId` | Ressource concernée. |
| `result`, `failureReason` | `SUCCESS`, `FAILURE` ou `DENIED`, et cause d'échec. |
| `details` | Données propres à l'événement. |
| `accessContext` | `actorType`, `hdsRoles`, `superAdminBypass`, `customerWid`. |
| `previousHash`, `entryHash` | Chaînage HMAC-SHA256. |

### Rapport de conformité

| Champ | Description |
|---|---|
| `reportId` | Identifiant `rpt_…`. |
| `type` | `RGPD_COMPLIANCE`, `NIS2_INCIDENTS` ; `HDS_AUDIT` pour un PDF de type `hdsAudit`. |
| `status` | `GENERATING`, `COMPLETED`, `FAILED`. |
| `periodFrom`, `periodTo` | Période. |
| `generatedBy` | Auteur. |
| `data` | Contenu du rapport. |

### Revue d'accès

| Champ | Description |
|---|---|
| `reviewId` | Identifiant `rev_…`. |
| `name`, `description` | Libellé. |
| `status` | `PENDING`, `COMPLETED`. |
| `scope` | `vaultIds`, `userIds`. |
| `findings` | Partages examinés : `shareId`, `vaultId`, `recommendation` (`KEEP`, `REVOKE`, `DOWNGRADE`), `reviewedBy`, `reviewedAt`. |
| `createdBy`, `completedAt`, `completedBy` | Auteur et clôture. |

## Statuts d'un document

| Statut | Signification |
|---|---|
| `ACTIVE` | Document stocké, disponible. |
| `QUARANTINED` | Document stocké chiffré, que le contrôle antivirus n'a pas confirmé sain. |
| `SEALED` | Document figé. |
| `DELETED` | Document supprimé, purgé 30 jours plus tard. |
| `SOFT_DELETED` | Document supprimé avec son coffre, purgé 30 jours plus tard. |

`antivirusStatus` vaut `CLEAN` ou `QUARANTINED`.

## Opérations

Les listes renvoient `{ "data": [ … ], "meta": { "limit", "hasMore" } }`, sauf mention contraire.

### Coffres

::endpoint{method="POST" path="/api/hds/vaults"}

::endpoint{method="GET" path="/api/hds/vaults"}

Filtres `type`, `status`, `limit` (20 par défaut, 100 au plus).

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}"}

::endpoint{method="PATCH" path="/api/hds/vaults/{vaultId}"}

Corps : `label`, `metadata`, `status`.

::endpoint{method="DELETE" path="/api/hds/vaults/{vaultId}"}

Réponse : `{ "deleted": true, "vaultId": "vlt_…" }`.

### Exporter un coffre

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/export"}

Réponse : `exportVersion`, `exportedAt`, `vault`, `documents`, `consents`, `shares` (métadonnées uniquement).

### Documents

::endpoint{method="POST" path="/api/hds/vaults/{vaultId}/documents"}

Multipart : `file` (obligatoire, 100 Mo), `folderId`, `comment`. Réponse `201`.

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/documents"}

Filtres `folderId`, `limit`.

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/documents/{docId}"}

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/documents/{docId}/versions"}

::endpoint{method="DELETE" path="/api/hds/vaults/{vaultId}/documents/{docId}"}

Réponse : `{ "deleted": true, "docId", "hardDeleteScheduledAt" }`.

### Dossiers

::endpoint{method="POST" path="/api/hds/vaults/{vaultId}/folders"}

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/folders"}

Filtre `parentFolderId`. Réponse : tableau de dossiers.

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/folders/{folderId}"}

::endpoint{method="PATCH" path="/api/hds/vaults/{vaultId}/folders/{folderId}"}

::endpoint{method="DELETE" path="/api/hds/vaults/{vaultId}/folders/{folderId}"}

::endpoint{method="POST" path="/api/hds/vaults/{vaultId}/folders/{folderId}/move-document"}

Corps : `docId`, `targetFolderId`.

### Partages

::endpoint{method="POST" path="/api/hds/shares"}

Corps : `vaultId`, `targetUserId`, `level`.

::endpoint{method="GET" path="/api/hds/shares"}

Filtres `vaultId`, `targetUserId`, `active`, `limit`.

::endpoint{method="GET" path="/api/hds/shares/{shareId}"}

::endpoint{method="DELETE" path="/api/hds/shares/{shareId}"}

### Consentements

::endpoint{method="POST" path="/api/hds/vaults/{vaultId}/consents"}

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/consents"}

Filtres `patientId`, `status`, `limit`.

::endpoint{method="GET" path="/api/hds/vaults/{vaultId}/consents/{consentId}"}

### Accès d'urgence

::endpoint{method="POST" path="/api/hds/break-glass/vaults/{vaultId}"}

Corps : `justification` (20 caractères au moins).

::endpoint{method="GET" path="/api/hds/break-glass"}

Filtres `vaultId`, `status`, `limit` (50 par défaut, 200 au plus).

::endpoint{method="GET" path="/api/hds/break-glass/{breakGlassId}"}

::endpoint{method="DELETE" path="/api/hds/break-glass/{breakGlassId}"}

### Journal d'audit

::endpoint{method="GET" path="/api/hds/audit-logs"}

Filtres `eventType`, `eventCategory`, `from`, `to`, `limit` (50 par défaut, 200 au plus).

::endpoint{method="GET" path="/api/hds/audit-logs/integrity-check"}

Réponse : `valid`, `totalEntries`, `checkTimestamp`, et en cas de rupture `firstInvalidAt`, `details`.

### Conformité

::endpoint{method="GET" path="/api/hds/compliance/rgpd"}

::endpoint{method="GET" path="/api/hds/compliance/nis2"}

::endpoint{method="POST" path="/api/hds/compliance/reports"}

Corps : `type` (`RGPD_COMPLIANCE` ou `NIS2_INCIDENTS`), `periodFrom`, `periodTo`.

::endpoint{method="GET" path="/api/hds/compliance/reports"}

::endpoint{method="GET" path="/api/hds/compliance/reports/{reportId}"}

::endpoint{method="POST" path="/api/hds/admin/compliance/reports"}

Paramètres d'URL : `type` (`hdsAudit`, `rgpd`, `nis2`), `from`, `to`. Produit un PDF.

::endpoint{method="GET" path="/api/hds/admin/compliance/reports/{reportId}/download"}

Réponse : `reportId`, `url`, `expiresInSeconds` (600).

### Revues d'accès

::endpoint{method="POST" path="/api/hds/access-reviews"}

::endpoint{method="GET" path="/api/hds/access-reviews"}

::endpoint{method="GET" path="/api/hds/access-reviews/{reviewId}"}

::endpoint{method="POST" path="/api/hds/access-reviews/{reviewId}/findings"}

::endpoint{method="POST" path="/api/hds/access-reviews/{reviewId}/complete"}

### Alertes

::endpoint{method="GET" path="/api/hds/admin/alerts"}

::endpoint{method="POST" path="/api/hds/admin/alerts/check"}

::endpoint{method="POST" path="/api/hds/admin/alerts/{alertId}/acknowledge"}

### Sauvegardes

::endpoint{method="POST" path="/api/hds/admin/backup"}

::endpoint{method="GET" path="/api/hds/admin/backup"}

Paramètres `limit` (20 par défaut, 100 au plus), `cursor`.

::endpoint{method="GET" path="/api/hds/admin/backup/{backupId}"}

::endpoint{method="POST" path="/api/hds/admin/backup/{backupId}/restore"}

Paramètre `dryRun=true` pour un essai à blanc.

### Espace

::endpoint{method="GET" path="/api/hds/networks/{networkWid}"}

## Erreurs

Deux formats coexistent. Les refus prononcés à l'entrée de l'API publique suivent son format `{ "statusCode", "message", "error", "timestamp", "path" }`. Les erreurs du module HDS sont relayées telles quelles, au format `{ "statusCode", "message", "error" }`.

| Code | `message` | Cause |
|---|---|---|
| `400` | tableau de messages de validation | Champ manquant, inconnu ou mal typé. |
| `400` | `HDS network not provisioned or not active` | Espace du client inactif. |
| `400` | `Vault quota exceeded: …` / `Document quota exceeded: …` | Quota atteint. |
| `400` | `Patient information is required for PATIENT vault type` | Identité du patient manquante. |
| `400` | `TEMPORARY vault expiresAt must be between 24 hours and 90 days from now` | Date de fin hors bornes. |
| `401` | `Authentification requise: …` | Jeton absent ou invalide. |
| `403` | `Rôle(s) HDS requis: HDS_ADMIN, HDS_HEALTHCARE, HDS_MEDICAL, HDS_PATIENT, HDS_STORAGE, HDS_DELETE (mode: any)` | Aucun rôle HDS. |
| `403` | `Insufficient HDS permissions for this operation` | Le rôle ne permet pas l'opération. |
| `403` | `HDS path not allowed` | Chemin inconnu de l'API. |
| `403` | `Access denied to this network` | Espace d'un autre client. |
| `404` | `Vault not found: vlt_…` | Coffre inexistant ou inaccessible. |
| `408` | `Request timed out` | Traitement de plus de 30 s. |
| `413` | `Storage quota exceeded` | Quota de stockage atteint. |
| `413` | `File too large` | Fichier de plus de 100 Mo. |
| `429` | — | Limite de débit atteinte. |
| `503` | `Auth check unavailable` | Vérification de révocation du jeton momentanément indisponible. |
| `503` | `HDS service unavailable` | Module momentanément injoignable. |

## Limites

| Élément | Valeur |
|---|---|
| Taille d'un document | 100 Mo |
| Stockage par espace | 10 Go par défaut |
| Coffres par espace | 1 000 par défaut |
| Documents par espace | 50 000 par défaut |
| Coffre `TEMPORARY` | fin entre 24 h et 90 jours |
| Justification d'accès d'urgence | 20 caractères au moins |
| Purge d'un document supprimé | 30 jours |
| Délai de traitement | 30 s par opération |
| Lien de téléchargement d'un rapport PDF | 600 s |
| Alertes | conservées 24 h, dédoublonnées sur 1 h |
| Limites de débit (API publique, par IP) | 10 req/s, 100 req/min, 1 000 req/h |
