PD-72 — Plan d'implementation¶

1. Decoupe en composants¶

Architecture cible¶

src/modules/document-transfer/
├── document-transfer.module.ts            # Module NestJS, enregistrement BullMQ
├── entities/
│   └── document-transfer.entity.ts        # Entite TypeORM DocumentTransfer
├── enums/
│   ├── transfer-status.enum.ts            # PENDING, READY_FOR_TRANSFER, ...
│   ├── transfer-policy.enum.ts            # copy | transfer
│   └── transfer-error-code.enum.ts        # PRE-01..PRE-08
├── types/
│   └── branded-ids.ts                     # DocumentTransferId, VaultId, ProofId (branded)
├── interfaces/
│   ├── transfer-job.interface.ts          # Payload job BullMQ
│   └── transfer-events.interface.ts       # Contrat evenement TRANSFER_EMPLOYEE
├── services/
│   ├── document-transfer.service.ts       # Service principal (creation, queries)
│   ├── transfer-state-machine.service.ts  # Machine d'etats fermee (INV-08)
│   ├── transfer-orchestrator.service.ts   # Orchestration flux nominal (etapes 1-11)
│   ├── transfer-preconditions.service.ts  # Gardes preconditions (compte, cle, consentement)
│   ├── transfer-proof.service.ts          # Emission evenement, acte de remise, Merkle/TSA
│   ├── transfer-revocation.service.ts     # Revocation acces entreprise (policy transfer)
│   └── transfer-notification.service.ts   # Notification salarie (in-app + email neutre)
├── processors/
│   └── pre-transfer.processor.ts          # Worker BullMQ @Processor('pv:jobs:transfer')
├── listeners/
│   └── anchor-confirmation.listener.ts    # Ecoute confirmation batch -> ANCHOR_CONFIRMED
├── constants/
│   └── transfer.constants.ts              # MAX_RETRIES, BASE_DELAY, ANCHOR_TIMEOUT_HOURS
├── dto/
│   └── transfer-job.dto.ts                # Validation payload job
├── migrations/
│   └── XXXXXX-create-document-transfer.ts # Migration DDL
└── __tests__/
    ├── transfer-state-machine.spec.ts     # Tests unitaires machine d'etats
    ├── transfer-orchestrator.spec.ts      # Tests unitaires orchestration
    ├── transfer-preconditions.spec.ts     # Tests unitaires preconditions
    ├── transfer-proof.spec.ts             # Tests unitaires proof/audit
    ├── transfer-revocation.spec.ts        # Tests unitaires revocation
    ├── pre-transfer.processor.spec.ts     # Tests unitaires processor
    ├── pre-transfer.integration.spec.ts   # Tests integration (DB + queue)
    └── fixtures/
        └── transfer-fixtures.ts           # Factories et fixtures

Composants et responsabilites¶

2. Flux techniques¶

Flux N1 — Nominal (copy)¶

DocumentSealingService          PreTransferProcessor       TransferOrchestratorService
       |                               |                            |
       |-- DOCUMENT_SEALED event ------>|                            |
       |   (audit log source)          |                            |
       |                               |-- process(job) ----------->|
       |                               |                            |
       |                               |   TransferPreconditionsService
       |                               |            |
       |                               |            |<-- checkAll() -->|
       |                               |            |  compte actif?   |
       |                               |            |  cle certifiee?  |
       |                               |            |  consentement?   |
       |                               |            |  vault_id match? |
       |                               |            |                  |
       |                               |   TransferStateMachineService
       |                               |            |
       |                               |            |-- PENDING -> READY_FOR_TRANSFER
       |                               |            |-- READY_FOR_TRANSFER -> TRANSFER_IN_PROGRESS
       |                               |            |
       |                               |   PreService (PD-41)
       |                               |            |
       |                               |            |-- reEncrypt(wrap_Entreprise, rk)
       |                               |            |-- zeroize(rk) immediate
       |                               |            |
       |                               |            |-- TRANSFER_IN_PROGRESS -> TRANSFERRED
       |                               |            |
       |                               |   TransferProofService
       |                               |            |
       |                               |            |-- createEvent(TRANSFER_EMPLOYEE)
       |                               |            |-- signHSM(event)
       |                               |            |-- includeMerkle(event)
       |                               |            |-- timestampTSA(event)
       |                               |            |-- scheduleAnchor(batch)
       |                               |            |-- generateActeRemise()
       |                               |            |
       |                               |            |-- TRANSFERRED -> PROOF_PENDING_ANCHOR
       |                               |            |
       |                               |   TransferNotificationService
       |                               |            |
       |                               |            |-- notifySalarie(in-app + email neutre)
       |                               |            |
       |                               |<-- OK (PROOF_PENDING_ANCHOR) ---|

Flux N2 — Confirmation ancrage (asynchrone)¶

AnchorBatchProcessor (PD-55)    AnchorConfirmationListener    TransferStateMachineService
       |                               |                            |
       |-- batch FINALIZED ----------->|                            |
       |   (event/callback)            |                            |
       |                               |-- findByProofId() -------->|
       |                               |                            |
       |                               |-- transition() ----------->|
       |                               |   PROOF_PENDING_ANCHOR     |
       |                               |   -> ANCHOR_CONFIRMED      |
       |                               |                            |
       |                               |-- setCompletedAt() ------->|

Flux E1 — Erreur recuperable (HSM/TSA)¶

PreTransferProcessor            TransferOrchestratorService
       |                               |
       |-- process(job) -------------->|
       |                               |-- ... erreur HSM/TSA ...
       |                               |-- transition -> FAILED
       |                               |-- retry_count < 3 ?
       |                               |   OUI: throw pour retry BullMQ
       |                               |   NON: FAILED terminal, escalade
       |<-- throw (BullMQ retry) ------|
       |                               |
       |-- backoff: 30s * 2^count ---->|
       |-- process(job) retry -------->|

Flux E2 — Replay idempotent¶

PreTransferProcessor            TransferOrchestratorService
       |                               |
       |-- process(job) -------------->|
       |                               |-- findByDocumentId()
       |                               |-- status in terminal?
       |                               |   OUI: rejet PRE-06 (log replay + code retour)
       |                               |   NON: reprise etat courant
       |<-- OK (idempotent) -----------|

2bis. Diagrammes Mermaid¶

Graphe de dependances inter-composants¶

graph TD
    subgraph "PD-72 — DocumentTransferModule"
        PROC[PreTransferProcessor]
        ORCH[TransferOrchestratorService]
        SM[TransferStateMachineService]
        PREC[TransferPreconditionsService]
        PROOF[TransferProofService]
        REVOC[TransferRevocationService]
        NOTIF[TransferNotificationService]
        LISTEN[AnchorConfirmationListener]
        SVC[DocumentTransferService]
        ENTITY[(DocumentTransfer entity)]
    end

    subgraph "Modules externes"
        PRE["PreService (PD-41)"]
        AUDIT["AuditService (PD-31)"]
        HSM["HsmService (PD-37)"]
        TSA["TsaService (PD-39)"]
        MERKLE["MerkleService (PD-54)"]
        ANCHOR["AnchorService (PD-55)"]
        NOTIF_EXT["NotificationService (PD-105)"]
        DOC["DocumentSecure entity"]
    end

    PROC -->|"delegue process(job)"| ORCH
    ORCH --> SM
    ORCH --> PREC
    ORCH --> PROOF
    ORCH -->|"si policy=transfer"| REVOC
    ORCH --> NOTIF
    ORCH -->|"reEncrypt()"| PRE
    ORCH --> SVC
    SVC --> ENTITY
    PREC --> DOC

    PROOF --> AUDIT
    PROOF --> HSM
    PROOF --> TSA
    PROOF --> MERKLE
    PROOF --> ANCHOR

    NOTIF --> NOTIF_EXT

    LISTEN -->|"batch FINALIZED"| SM
    LISTEN --> SVC

    style PROC fill:#4a86c8,color:#fff
    style ORCH fill:#4a86c8,color:#fff
    style SM fill:#e8a735,color:#fff
    style PROOF fill:#d64045,color:#fff
    style ENTITY fill:#6c757d,color:#fff

Diagramme de sequence — Flux nominal (copy)¶

sequenceDiagram
    participant Seal as DocumentSealingService
    participant Queue as BullMQ pv:jobs:transfer
    participant Proc as PreTransferProcessor
    participant Orch as TransferOrchestratorService
    participant SM as TransferStateMachineService
    participant Prec as TransferPreconditionsService
    participant PRE as PreService (PD-41)
    participant Proof as TransferProofService
    participant HSM as HsmService (PD-37)
    participant TSA as TsaService (PD-39)
    participant Merkle as MerkleService (PD-54)
    participant Anchor as AnchorService (PD-55)
    participant Notif as TransferNotificationService

    Seal->>Queue: DOCUMENT_SEALED event
    Queue->>Proc: process(job)
    Proc->>Orch: execute(job.data)

    rect rgb(230, 245, 255)
        Note over Orch,Prec: Phase 1 — Preconditions
        Orch->>Prec: checkAll(payload)
        Prec-->>Orch: OK (compte actif, cle certifiee, consentement, vault_id)
    end

    rect rgb(230, 255, 230)
        Note over Orch,PRE: Phase 2 — Re-chiffrement PRE
        Orch->>SM: transition(PENDING → READY_FOR_TRANSFER)
        Orch->>SM: transition(READY_FOR_TRANSFER → TRANSFER_IN_PROGRESS)
        Orch->>PRE: reEncrypt(wrap_Entreprise, rk)
        PRE-->>Orch: wrap_Salarie
        Note over Orch: zeroize(rk) dans finally
        Orch->>SM: transition(TRANSFER_IN_PROGRESS → TRANSFERRED)
    end

    rect rgb(255, 240, 230)
        Note over Orch,Anchor: Phase 3 — Preuve probatoire
        Orch->>Proof: createTransferProof()
        Proof->>HSM: sign(event_hash)
        HSM-->>Proof: signature
        Proof->>Merkle: include(event)
        Merkle-->>Proof: merkle_proof
        Proof->>TSA: timestamp(event)
        TSA-->>Proof: tsa_token
        Proof->>Anchor: schedule(batch)
        Proof-->>Orch: proof_id
        Orch->>SM: transition(TRANSFERRED → PROOF_PENDING_ANCHOR)
    end

    rect rgb(245, 230, 255)
        Note over Orch,Notif: Phase 4 — Notification
        Orch->>Notif: notifySalarie(transfer_ref)
        Notif-->>Orch: OK
    end

    Orch-->>Proc: OK (PROOF_PENDING_ANCHOR)

Diagramme de sequence — Confirmation ancrage (asynchrone)¶

sequenceDiagram
    participant Batch as AnchorBatchProcessor (PD-55)
    participant Listen as AnchorConfirmationListener
    participant SM as TransferStateMachineService
    participant SVC as DocumentTransferService

    Batch->>Listen: batch FINALIZED (tx_id)
    Listen->>SVC: findByProofId(proof_id)
    SVC-->>Listen: DocumentTransfer (PROOF_PENDING_ANCHOR)
    Listen->>SM: transition(PROOF_PENDING_ANCHOR → ANCHOR_CONFIRMED)
    Listen->>SVC: setCompletedAt(now)
    Note over Listen: Transfert termine

Machine d'etats — Transitions autorisees¶

stateDiagram-v2
    [*] --> PENDING: DOCUMENT_SEALED recu

    PENDING --> READY_FOR_TRANSFER: Preconditions OK
    PENDING --> BLOCKED_WAITING_CONSENT: Compte absent (PRE-01)
    PENDING --> FAILED: Cle invalide (PRE-02)

    BLOCKED_WAITING_CONSENT --> READY_FOR_TRANSFER: Consentement valide

    READY_FOR_TRANSFER --> TRANSFER_IN_PROGRESS: Debut re-chiffrement

    TRANSFER_IN_PROGRESS --> TRANSFERRED: Re-chiffrement OK
    TRANSFER_IN_PROGRESS --> FAILED: Erreur (retry < 3)

    TRANSFERRED --> PROOF_PENDING_ANCHOR: Preuve emise

    PROOF_PENDING_ANCHOR --> ANCHOR_CONFIRMED: Batch finalise
    PROOF_PENDING_ANCHOR --> FAILED: Timeout ancrage

    FAILED --> PENDING: Retry (count < MAX)

    ANCHOR_CONFIRMED --> [*]

3. Mapping invariants -> mecanismes¶

4. Mapping criteres d'acceptation -> mecanismes¶

5. Mapping tests (TC-*) -> mecanismes + observables¶

6. Gestion des erreurs¶

Strategie de retry (backoff exponentiel)¶

// Dans PreTransferProcessor
const backoffDelay = TRANSFER_CONSTANTS.BASE_DELAY_MS * Math.pow(2, transfer.retry_count);
// BASE_DELAY_MS = 30_000 (30s)
// retry 0: 30s, retry 1: 60s, retry 2: 120s

Erreurs non recuperables (PRE-02, PRE-07) : FAILED terminal immediat, pas de retry.

7. Impacts securite¶

IDs aleatoires¶

Tous les UUIDs generes via crypto.randomUUID() (learning PD-63). Typage branded :

type DocumentTransferId = string & { readonly __brand: 'DocumentTransferId' };
type VaultId = string & { readonly __brand: 'VaultId' };
type ProofId = string & { readonly __brand: 'ProofId' };

8. Hypotheses techniques¶

9. Points de vigilance (risques, dette, pieges)¶

1. Zeroization fiable : JavaScript n'offre pas de garantie formelle de zeroization memoire (GC, optimisations V8). Le pattern buffer.fill(0) + null est le meilleur effort. Pour une garantie HSM-grade, les secrets doivent rester dans le HSM (c'est le cas de K_doc). Le rk est le seul secret temporaire manipule cote Node.js.

2. Couplage modules externes : L'orchestrateur depend de 6+ modules (PRE, HSM, TSA, Merkle, anchoring, audit). Chaque module est injecte via interface NestJS. Les tests unitaires mockent chaque dependance. Les tests d'integration valident les interactions reelles.

3. Machine d'etats exhaustive : La spec definit 8 etats et ~10 transitions autorisees. Le service doit couvrir les 8x8=64 combinaisons possibles (10 autorisees, 54 interdites). Les tests TC-INV-08 et TC-NR-02 couvrent les interdictions.

4. Timeout ancrage configurable : ANCHOR_TIMEOUT_HOURS (defaut 24h, min 1h, max 72h) via variable d'environnement. Le cron/listener de timeout doit etre resilient aux redemarrages (verification basee sur created_at en DB, pas sur timer en memoire).

5. Notification anti-spam : Deduplication par DocumentTransfer.id pour la notification RH (BLOCKED_WAITING_CONSENT). Un seul email par transfert bloque.

6. Verrouillage pessimiste : Utiliser SELECT FOR UPDATE pour proteger contre les replays concurrents (TC-NEG-04). Attention au deadlock si plusieurs transferts pour le meme document.

7. Migration DDL : Nouvelle table vault_secure.document_transfers. Aucune modification de table existante. Les enum types PostgreSQL (transfer_status, transfer_policy) sont crees dans la migration.

8. ALTER TYPE ADD VALUE : Si les enums sont ajoutes a un type existant (peu probable ici — types nouveaux), respecter le pattern commitTransaction() avant utilisation (learning PD-282/PD-279).

10. Perimetre de test¶

Tous les niveaux de test intra-module sont couverts. L'E2E cross-module est reporte aux tests d'integration avec mocks des interfaces PD-41/PD-37/PD-39/PD-54/PD-55.

Couverture minimale attendue : >= 80% sur le perimetre in scope.

Framework de test : Jest (configuré dans le projet ProbatioVault-backend existant, jest.config.ts). Runner CJS-compatible. Les modules ESM-only (si presents) sont transformes via ts-jest.

Ancre temporelle timeout ancrage : Le timeout ANCHOR_TIMEOUT_HOURS est calcule depuis le timestamp de transition vers PROOF_PENDING_ANCHOR (champ updated_at de DocumentTransfer), pas depuis created_at.

11. Hors perimetre¶

• Implementation interne des primitives cryptographiques (PRE/HSM/TSA/Merkle/blockchain) — modules existants.
• UX de consentement salarie — suppose employee_consent = TRUE au moment nominal.
• Format interne du proof_bundle.json (ProofEnvelope canonical existant).
• Validation juridique externe de l'opposabilite probatoire.
• Interface REST/HTTP pour declencher un transfert — le declenchement est exclusivement par evenement interne DOCUMENT_SEALED.
• Modification des routes d'autres modules : aucune modification d'autres modules. PD-72 est un flux asynchrone interne (worker BullMQ) sans route HTTP cross-module a proteger.

12. Mecanismes cross-module¶

Aucune modification d'autres modules. PD-72 consomme les services existants via injection de dependances NestJS :