PD-85 — Plan d'implémentation¶

1. Découpage en composants¶

C1 — export-dto : DTOs de requête et de réponse¶

Responsabilité : Validation d'entrée (ComplaintFileRequestDto) et sérialisation de sortie (ComplaintFileResponseDto, ManifestDto, ChronologyDto, RejectedProofDto).

• ComplaintFileRequestDto : proofIds: UUID[] (1..500), validé par class-validator (regex UUID v4, @ArrayMinSize(1), @ArrayMaxSize(500), @ArrayUnique()).
• ComplaintFileResponseDto : payload 200 complet (exportId, manifest, chronology, signedUrls, guideUrl, readmeVerification, rejectedProofs).
• ManifestDto : version, exportId, exportedAt, exportedBy, proofCount, proofs[], integrityHash.
• ChronologyDto : events[] triés par timestamp non décroissant.
• RejectedProofDto : proofId, reason.

C2 — export-exceptions : Codes d'erreur métier PD-85¶

Responsabilité : ExportException étendant HttpException avec codes machine-readable.

C3 — export-validators : Validations invariants RFC par preuve¶

Responsabilité : Implémentation des 5 validations RFC (INV-02, INV-03, INV-09, INV-11, INV-12) sur chaque ProofEnvelope. Retourne {valid: boolean, reason?: string} par preuve.

• FiveSectionsCompleteValidator : vérifie les 5 sections RFC présentes et non vides.
• ReKeyActiveValidator : vérifie qu'aucun ReKey actif n'existe sur la preuve.
• SecretExposureValidator : scan déterministe des patterns sensibles (DEK, ReKey fragments, mots de passe).
• EnvelopeSealValidator : vérifie la validité cryptographique du sceau HSM.
• OfflineMaterialValidator : vérifie la présence du matériel de vérification offline.

C4 — export-service : Service d'orchestration export¶

Responsabilité : Logique métier principale. Orchestre la chaîne complète : validation requête → contrôle plan → RLS ownership → validation invariants → calcul taille → génération manifest/chronology → URLs signées → audit WORM.

• Traitement synchrone (pas de queue/worker).
• Rejet partiel : les preuves invalides sont exclues du manifest et collectées dans rejectedProofs.
• Fail-fast sur 404 : la première preuve non possédée/inexistante interrompt le traitement.
• Audit : événement WORM émis pour TOUT résultat (200, 400, 403, 404, 413, 422).

C5 — export-manifest-builder : Construction manifest + chronology¶

Responsabilité : Assemblage du manifest.json (avec integrityHash SHA3-256 JCS) et du chronology.json (événements triés). Construction du README_VERIFICATION.txt.

• Canonicalisation via json-canonicalize (RFC 8785) — réutilisation du service existant tsa/utils/canonical-json.utils.ts.
• Hash SHA3-256 via node:crypto (createHash('sha3-256')), pas SHA-256 (différent du TSA existant qui utilise SHA-256).
• Champ integrityHash exclu de la canonicalisation avant calcul du hash.

C6 — export-controller : Endpoint REST¶

Responsabilité : Remplacement du stub PD-84 ExportController par l'implémentation réelle. Endpoint POST /exports/complaint-file (nouvelle route, distincte des stubs folders/:id/exports/*).

• Guards : OidcJwtAuthGuard (auth) + PremiumGuard (plan).
• Rate limiting : EXPORT_RATE_LIMIT_PER_HOUR (défaut 10, configurable).
• Injection du ExportService.

C7 — export-config : Configuration et constantes¶

Responsabilité : Variables d'environnement et constantes PD-85.

C8 — export-audit : Extension audit WORM¶

Responsabilité : Ajout du type EXPORT_GENERATED à AuditActionType et émission des événements audit pour chaque appel (succès ET erreurs). Champs obligatoires : actorId, exportId, proofCount, result (état terminal), timestamp_utc, correlationId.

C9 — export-minor-evidence : Évidences B2C-mineurs¶

Responsabilité : Enrichissement conditionnel du payload export avec les évidences mineur/représentant légal (Mandate, Dual Validation, ReKey Lifecycle). Consultation des données existantes du module dual-validation et freemium.

C10 — export-tests : Tests unitaires et d'intégration¶

Responsabilité : Couverture complète des TC-* du cahier de tests.

2. Flux techniques¶

F1 — Export nominal complet (200, rejectedProofs=[])¶

Client → POST /exports/complaint-file {proofIds}
  → OidcJwtAuthGuard (auth)
  → PremiumGuard (plan != FREE → 403 sinon)
  → ExportController.createComplaintFile()
    → ExportService.execute(userId, proofIds)
      1. Validation DTO (proofIds format, doublons → 400)
      2. RLS ownership check (fail-fast → 404)
      3. Chargement ProofEnvelopes depuis DB
      4. Validation invariants RFC par preuve (5 validators)
         → Si toutes invalides → 422
         → Sinon → partition valides/rejetées
      5. Calcul taille totale chiffrée → si > 1 GB → 413
      6. ExportManifestBuilder.build(validProofs, userId, role)
         → manifest.json (JCS canonicalisé + SHA3-256 integrityHash)
         → chronology.json (events triés)
         → README_VERIFICATION.txt (asset statique)
      7. S3PresignService.getSignedUrl() pour chaque document chiffré
         → TTL configurable (défaut 15 min, max 30 min)
      8. Guide statique guideUrl (asset serveur)
      9. Audit WORM (EXPORT_GENERATED, fail-closed)
    → Response 200 {exportId, manifest, chronology, signedUrls, guideUrl, readmeVerification, rejectedProofs=[]}

F2 — Export partiel avec rejets (200, rejectedProofs non vide)¶

Identique à F1, étapes 1-3, puis à l'étape 4 certaines preuves sont rejetées. Les preuves rejetées sont collectées avec motif, les valides continuent le flux F1 (étapes 5-9). proofCount = nombre de valides uniquement.

F3 — Cas mineur/représentant légal¶

À l'étape 6 du flux F1, ExportMinorEvidenceService est invoqué conditionnellement : - Si user.accountRole == LEGAL_GUARDIAN → exportedBy.role = LEGAL_GUARDIAN - Si dossier mineur actif → enrichissement avec évidences (Mandate si présent, Dual Validation si présent, ReKey Lifecycle si présent) - Aucune évidence non applicable n'est ajoutée (test TC-NOM-03)

2bis. Diagrammes Mermaid¶

Graphe de dépendances entre composants¶

graph TD
    C6["C6 — export-controller<br/>(endpoint REST)"]
    C4["C4 — export-service<br/>(orchestration)"]
    C1["C1 — export-dto<br/>(DTOs)"]
    C2["C2 — export-exceptions<br/>(erreurs métier)"]
    C3["C3 — export-validators<br/>(validations RFC)"]
    C5["C5 — export-manifest-builder<br/>(manifest + chronology)"]
    C7["C7 — export-config<br/>(configuration)"]
    C8["C8 — export-audit<br/>(audit WORM)"]
    C9["C9 — export-minor-evidence<br/>(évidences B2C-mineurs)"]
    C10["C10 — export-tests<br/>(tests)"]

    C6 --> C4
    C6 --> C1
    C6 --> C7
    C4 --> C1
    C4 --> C2
    C4 --> C3
    C4 --> C5
    C4 --> C7
    C4 --> C8
    C4 --> C9
    C5 --> C7
    C10 -.->|teste| C1
    C10 -.->|teste| C2
    C10 -.->|teste| C3
    C10 -.->|teste| C4
    C10 -.->|teste| C5
    C10 -.->|teste| C6
    C10 -.->|teste| C8
    C10 -.->|teste| C9

    EXT_S3["S3PresignService<br/>(PD-46)"]
    EXT_AUDIT["AuditLogService<br/>(existant)"]
    EXT_FREEMIUM["FreemiumModule<br/>(PD-84)"]
    EXT_PROOF["ProofEnvelopeRepo<br/>(legal-pre)"]
    EXT_DUAL["DualValidationRepo<br/>(dual-validation)"]

    C4 --> EXT_S3
    C8 --> EXT_AUDIT
    C6 --> EXT_FREEMIUM
    C4 --> EXT_PROOF
    C9 --> EXT_DUAL

    style C6 fill:#4a90d9,color:#fff
    style C4 fill:#d94a4a,color:#fff
    style C3 fill:#d9a44a,color:#fff
    style C5 fill:#4ad98a,color:#fff
    style EXT_S3 fill:#888,color:#fff
    style EXT_AUDIT fill:#888,color:#fff
    style EXT_FREEMIUM fill:#888,color:#fff
    style EXT_PROOF fill:#888,color:#fff
    style EXT_DUAL fill:#888,color:#fff

Diagramme de séquence — Flux nominal F1 (export complet)¶

sequenceDiagram
    participant Client
    participant C6 as C6 — ExportController
    participant Auth as OidcJwtAuthGuard
    participant Plan as PremiumGuard (C6/PD-84)
    participant C4 as C4 — ExportService
    participant DB as ProofEnvelopeRepo (legal-pre)
    participant C3 as C3 — Validators (x5)
    participant C5 as C5 — ManifestBuilder
    participant C9 as C9 — MinorEvidence
    participant S3 as S3PresignService (PD-46)
    participant C8 as C8 — ExportAudit
    participant Audit as AuditLogService (existant)

    Client->>C6: POST /exports/complaint-file {proofIds}
    C6->>Auth: JWT validation
    Auth-->>C6: userId
    C6->>Plan: plan != FREE ?
    Plan-->>C6: OK (ou 403)

    C6->>C4: execute(userId, proofIds)

    Note over C4: 1. Validation DTO (C1)
    C4->>DB: findByIds(proofIds) WHERE user_id = userId
    DB-->>C4: ProofEnvelopes (ou 404 fail-fast)

    Note over C4: 4. Validation invariants RFC
    loop Pour chaque preuve
        C4->>C3: validate(envelope)
        C3-->>C4: {valid, reason?}
    end
    Note over C4: Partition valides / rejetées

    Note over C4: 5. Calcul taille (> 1 GB -> 413)

    C4->>C9: enrichIfMinor(userId, validProofs)
    C9-->>C4: évidences conditionnelles

    C4->>C5: build(validProofs, userId, role, evidences)
    C5-->>C4: manifest + chronology + README

    loop Pour chaque document chiffré
        C4->>S3: getSignedUrl(s3Key, ttl)
        S3-->>C4: signedUrl
    end

    C4->>C8: emitExportAudit(exportId, result=SUCCESS)
    C8->>Audit: logAsync(EXPORT_GENERATED, ...)
    Audit-->>C8: OK (ou 500 fail-closed)
    C8-->>C4: OK

    C4-->>C6: {exportId, manifest, chronology, signedUrls, ...}
    C6-->>Client: 200 ComplaintFileResponseDto

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Fail-closed audit : si AuditLogService.logAsync() échoue, l'export DOIT échouer (500). L'opération métier et l'audit sont atomiques au niveau applicatif — un export sans trace audit violerait INV-85-05.

7. Impacts sécurité¶

Zero-Knowledge (INV-85-01)¶

L'endpoint POST /exports/complaint-file ne lit JAMAIS le contenu des documents. Il : - Lit les métadonnées des ProofEnvelopes depuis PostgreSQL (structures, hashes, seals) - Génère des URLs signées S3 via S3PresignService (opération de signature, pas de GetObject) - Assemble le manifest/chronology à partir des métadonnées uniquement

Mécanisme de vérification : Revue statique du code + test TC-INV-8501 (grep absence GetObject, decrypt, decipher).

Authentification et autorisation¶

• OidcJwtAuthGuard : auth JWT Keycloak (existant)
• PremiumGuard : vérifie user.plan != FREE (nouveau, inspiré de PlanStubGuard)
• RLS ownership : WHERE proof.user_id = :userId (PostgreSQL RLS + vérification applicative, défense en profondeur)
• Rate limiting : @nestjs/throttler par utilisateur (EXPORT_RATE_LIMIT_PER_HOUR)

Données sensibles¶

• Aucun secret (DEK, K_master, fragments ReKey) dans le payload de réponse (INV-09)
• SecretExposureValidator scanne le payload sérialisé avant émission
• Les URLs signées contiennent des credentials temporaires (S3 HMAC) — TTL borné ≤ 30 min

Journalisation¶

• Audit WORM pour TOUT résultat (succès + erreurs), fail-closed
• Champs : actorId, exportId, proofIds, proofCount, result, rejectedCount, timestamp_utc, correlationId
• Aucune donnée sensible dans les logs (pas de contenu document, pas de clés)

Conformité¶

• Art. 1366 Code civil : auto-vérifiabilité via integrityHash + matériel offline
• NF Z42-013 / ISO 14641 : audit WORM immuable
• eIDAS : matériel de vérification embarqué (PD-282)

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

SHA3-256 vs SHA-256¶

Le codebase existant (tsa/utils/canonical-json.utils.ts) utilise SHA-256 (sha256Hash). PD-85 requiert SHA3-256 pour integrityHash. Ne PAS réutiliser canonicalizeAndHash() directement — créer une fonction sha3_256Hash() dédiée ou utiliser createHash('sha3-256') directement.

Fail-fast 404 vs rejets partiels¶

Le 404 (proof non possédée/inexistante) est fail-fast : le traitement s'arrête à la première erreur. Les rejets partiels (422/200) ne s'appliquent qu'aux validations d'invariants RFC (INV-02/03/09/11/12), PAS à l'ownership. L'ordre de traitement est critique : 1. Validation payload (400) 2. Contrôle plan (403) 3. RLS ownership — fail-fast (404) 4. Validation taille (413) 5. Validation invariants RFC — rejet partiel (200 ou 422)

Signature ECDSA raw pour INV-11¶

Attention au piège double-hash (REX PD-282) : CloudHSM signe en mode CKM_ECDSA (raw). Utiliser crypto.verify(null, hash, publicKey, signature), jamais createVerify('SHA3-384').update(hash).

Rate limiting¶

Le rate limit (10/h par défaut) doit être par utilisateur, pas global. Utiliser @nestjs/throttler avec la clé userId extraite du JWT.

Atomicité audit¶

L'audit est fail-closed : si l'écriture WORM échoue, l'export doit échouer (500). Cela implique que AuditLogService.logAsync() doit être attendu (await) malgré son nom async — il s'agit d'un fire-and-await, pas d'un fire-and-forget pour cet usage.

Doublons proofIds¶

La spec contractualise le rejet 400 pour les doublons (pas de déduplication). Le DTO doit utiliser @ArrayUnique() de class-validator.

10. Hors périmètre¶

• Assemblage ZIP : PD-283 (côté app).
• Déchiffrement documents : interdit (Zero-Knowledge).
• Script de vérification automatisé : V2.
• Timeline PDF riche : V2.
• Internationalisation du guide : V2.
• Notification automatique : V2.
• Tests de performance P95 : contexte matériel non spécifié (cf. H-06 spec). Les seuils 5s/50 preuves et 10s/100 preuves sont documentés mais non testables sans environnement de référence.
• Migration DDL : aucun changement de schéma contractualisé. Si encrypted_size manque sur les entités, c'est une adaptation d'implémentation (HT-03), pas un changement de spec.

Périmètre de test¶

Tous les niveaux de test sont couverts, aucune exclusion. Les tests d'intégration S3 (TC-NOM-06, TC-NOM-07) utilisent un mock S3 local (localstack ou mock S3PresignService). Les tests E2E vérifient le flux HTTP complet avec base de données réelle.

Mécanismes cross-module¶

Aucune modification de routes d'autres modules.