PD-177 — Plan d'implementation detaille¶

Version : 1.1 (corrections Gate 5 v1 — 8 ecarts resolus : NE-05-01 a NE-05-08) Date : 2026-02-23 Statut : DRAFT — En attente re-gate v2 Dependances : PD-52 (done), PD-55 (done), PD-53 (interface), PD-245 (interface)

Table des matieres¶

1. Decoupage en composants
2. Flux d'implementation
3. Mapping invariants → mecanismes techniques
4. Mapping criteres d'acceptation → mecanismes + tests
5. Mapping erreurs → BlockchainErrorCode
6. Contraintes techniques
7. Securite
8. Hypotheses d'implementation
9. Points de vigilance

1. Decoupage en composants¶

1.1 Composants modifies (code existant)¶

1.2 Composants nouveaux¶

1.3 Composants documentaires¶

2. Flux d'implementation¶

2.1 Phases d'implementation (ordre strict)¶

Phase 0 : Prerequis (pas de code, validation config)
  └─ Verifier que la config existante supporte les valeurs PD-177
     (confirmations Polygon=12, Arbitrum=30, timeout=900s)

Phase 1 : Fondations (aucune dependance inter-composants PD-177)
  ├─ [C-01] Ajout error codes dans BlockchainErrorCode
  ├─ [N-07] NetworkConfirmationPolicy (constantes)
  ├─ [C-07] Enrichir NetworkConfig avec confirmationTimeoutMs
  └─ [C-08] Ajouter signerAddress dans TransactionResult DTO

Phase 2 : Schema et persistance
  ├─ [N-06] Migration AddSignerAddress
  ├─ [C-03] Enrichir AnchorBatch entity
  └─ Validation locale migration (INV-177-20)

Phase 3 : Services core
  ├─ [N-01] CustodyModeGuard (gate S2)
  ├─ [N-02] SecretLeakInterceptor
  ├─ [C-02] ConfirmationTracker (timeout configurable)
  ├─ [C-06] TransactionService (retour signer_address)
  ├─ [N-03] WalletOperationalService
  └─ [N-08] AnchorExclusivityGuard

Phase 4 : Integration ancrage
  ├─ [C-05] BlockchainAdapterService (signer_address + network)
  ├─ [C-04] BlockchainAnchorProcessor (confirmations dynamiques)
  ├─ [C-11] AnchorBatchService (signer_address, append-only)
  ├─ [C-09] ProofArtifactDto (champ blockchain)
  └─ [N-04] AnchorProofValidator

Phase 5 : Continuite et resilience
  ├─ [N-05] WalletRecoveryService
  └─ [D-01, D-02] Documentation operationnelle

Phase 6 : Wiring module
  └─ [C-10] BlockchainModule exports + AnchorModule providers

2.2 Graphe de dependances¶

N-07 ──► C-07 ──► C-02 (timeout configurable utilise la config enrichie)
C-01 ──► N-02 (interceptor utilise les error codes)
C-01 ──► N-04 (proof validator utilise PROOF_LINK_INCOMPLETE)
C-08 ──► C-06 (TransactionService retourne le DTO enrichi)
C-08 ──► C-05 (Adapter retourne le DTO enrichi)
N-06 ──► C-03 (entity apres migration)
C-03 ──► C-11 (batch service ecrit signer_address)
N-01 ──► N-03 (WalletOperationalService utilise le guard)
N-03 ──► C-04 (processor delegue a WalletOperationalService)

2.3 Diagrammes Mermaid¶

2.3.1 Graphe de dependances des composants¶

graph TD
    subgraph "Phase 1 — Fondations"
        C01["C-01 BlockchainErrorCode"]
        N07["N-07 NetworkConfirmationPolicy"]
        C07["C-07 blockchain.config.ts"]
        C08["C-08 TransactionResult DTO"]
    end

    subgraph "Phase 2 — Schema"
        N06["N-06 Migration AddSignerAddress"]
        C03["C-03 AnchorBatch entity"]
    end

    subgraph "Phase 3 — Services core"
        N01["N-01 CustodyModeGuard"]
        N02["N-02 SecretLeakInterceptor"]
        C02["C-02 ConfirmationTracker"]
        C06["C-06 TransactionService"]
        N03["N-03 WalletOperationalService"]
        N08["N-08 AnchorExclusivityGuard"]
    end

    subgraph "Phase 4 — Integration ancrage"
        C05["C-05 BlockchainAdapterService"]
        C04["C-04 BlockchainAnchorProcessor"]
        C11["C-11 AnchorBatchService"]
        C09["C-09 ProofArtifactDto"]
        N04["N-04 AnchorProofValidator"]
    end

    subgraph "Phase 5 — Continuite"
        N05["N-05 WalletRecoveryService"]
        D01["D-01 Runbook reprise"]
        D02["D-02 Registre rotations"]
    end

    subgraph "Phase 6 — Wiring"
        C10["C-10 BlockchainModule"]
    end

    N07 --> C07
    C07 --> C02
    C01 --> N02
    C01 --> N04
    C08 --> C06
    C08 --> C05
    N06 --> C03
    C03 --> C11
    N01 --> N03
    N03 --> C04
    C06 --> C05
    C05 --> C04
    C11 --> C04
    N08 --> N03
    C04 --> C10
    N03 --> C10

2.3.2 Sequence d'ancrage (flux principal)¶

sequenceDiagram
    participant Worker as BlockchainAnchorProcessor<br/>(C-04)
    participant Wallet as WalletOperationalService<br/>(N-03)
    participant Guard as CustodyModeGuard<br/>(N-01)
    participant ExclGuard as AnchorExclusivityGuard<br/>(N-08)
    participant Adapter as BlockchainAdapterService<br/>(C-05)
    participant TxService as TransactionService<br/>(C-06)
    participant Custody as CustodyService<br/>(PD-52)
    participant KMS as AWS KMS
    participant Tracker as ConfirmationTracker<br/>(C-02)
    participant BatchSvc as AnchorBatchService<br/>(C-11)
    participant Validator as AnchorProofValidator<br/>(N-04)

    Worker->>Wallet: submitMerkleRoot(merkleRoot, network)
    Wallet->>Guard: assertMode(S2)
    Guard-->>Wallet: OK
    Wallet->>ExclGuard: assertAnchorContext()
    ExclGuard-->>Wallet: OK
    Wallet->>Adapter: submitMerkleRoot(merkleRoot, network)
    Adapter->>TxService: sendAnchorTransaction(data, network)
    TxService->>Custody: getStrategy().signTransaction(tx)
    Custody->>KMS: kms:Sign(ECC_SECG_P256K1)
    KMS-->>Custody: signature
    Custody-->>TxService: signedTx
    TxService-->>Adapter: TransactionResult{hash, signerAddress}
    Adapter->>Tracker: track(txHash, network)
    Note over Tracker: NetworkConfirmationPolicy<br/>Polygon: 12 blocs / 900s<br/>Arbitrum: 30 blocs / 900s
    Tracker-->>Adapter: confirmation{blockNumber, confirmations}
    Adapter-->>Wallet: TransactionResult enrichi
    Wallet->>BatchSvc: submitBatch(merkleRoot, txHash, signerAddress, chainId)
    Note over BatchSvc: Append-only, validation<br/>signerAddress non-null
    BatchSvc-->>Wallet: AnchorBatch persiste
    Wallet->>Validator: validate(merkleRoot, txHash, confirmation)
    Validator-->>Wallet: OK (lien complet)
    Wallet-->>Worker: ProofArtifactDto{blockchain: 'ethereum_l2'}

2.3.3 Sequence anti-fuite (SecretLeakInterceptor)¶

sequenceDiagram
    participant Service as Service blockchain
    participant Interceptor as SecretLeakInterceptor<br/>(N-02)
    participant Channel as Canal sortie<br/>(log / API / trace)
    participant Audit as AuditService

    Service->>Interceptor: output (reponse ou log)
    Interceptor->>Interceptor: scanForSecrets(data)
    alt Pattern secret detecte
        Interceptor->>Audit: logEvent('SECURITY_INCIDENT', ...)
        Interceptor--xChannel: BLOQUE (throw SECRET_LEAK_DETECTED)
    else Aucun pattern
        Interceptor->>Channel: output transmis
    end

3. Mapping invariants → mecanismes techniques¶

4. Mapping criteres d'acceptation → mecanismes + tests¶

5. Mapping erreurs → BlockchainErrorCode¶

5.1 Resolution NE-01 (divergences spec vs code existant)¶

La spec PD-177 utilise des noms de codes d'erreur qui different du BlockchainErrorCode existant (PD-52). La strategie retenue est d'ajouter des aliases dans l'enum pour maintenir la compatibilite avec la spec sans casser le code existant.

5.2 Tableau complet ERR → Code¶

5.3 Modification de error-codes.ts¶

// Ajouts PD-177 dans BlockchainErrorCode
export enum BlockchainErrorCode {
  // ... codes PD-52 existants inchanges ...

  // PD-177: Custody mode gate (ERR-177-01)
  INVALID_CUSTODY_MODE = 'INVALID_CUSTODY_MODE',

  // PD-177: Signature failure at custody level (ERR-177-02)
  SIGNATURE_FAILED = 'SIGNATURE_FAILED',

  // PD-177: Incomplete proof chain (ERR-177-07)
  PROOF_LINK_INCOMPLETE = 'PROOF_LINK_INCOMPLETE',

  // PD-177: Reorg or abandonment (ERR-177-06)
  TRANSACTION_REORGED_OR_ABANDONED = 'TRANSACTION_REORGED_OR_ABANDONED',
}

6. Contraintes techniques¶

6.1 Dependances inter-stories¶

6.2 Framework de test¶

• Unite : Jest (existant, configure dans package.json)
• Integration : Jest avec *.integration.spec.ts pattern
• E2E : Jest avec test/jest-e2e.json
• Mocking :
• ioredis-mock pour BullMQ en tests unitaires
• jest.fn() pour les services (pattern existant)
• mockQueryRunner pour les transactions TypeORM
• Coverage : Seuils existants maintenus (80% branches, 85% functions/lines/statements)
• Path aliases : @/, @config/, @common/, @modules/ (resolus par moduleNameMapper)

6.3 ESM/CJS¶

• Le projet utilise CommonJS ("module": "nodenext" dans tsconfig mais NestJS 10 + ts-jest = CJS de facto)
• ethers@6.16.0 est ESM-first mais compatible CJS via les exports maps
• jose@6.1.3 est ESM et est mocke via __mocks__/jose.ts
• PD-177 ne change pas le mode de module : tous les fichiers PD-177 sont CJS conformes au reste du projet

6.4 Base de donnees¶

• ORM : TypeORM 0.3.17
• Schema : vault_blockchain
• Migration : TypeORM CLI (npm run migration:generate/run/validate)
• Prerequis PostgreSQL local : La validation de la migration (INV-177-20) necessite une instance PostgreSQL locale accessible. Les commandes npm run migration:validate et npm run migration:run se connectent a la base definie par DATABASE_URL dans .env local (ex: postgresql://postgres:postgres@localhost:5432/probatiovault_dev). Ce prerequis est obligatoire pour la Phase 2 du plan et la checklist pre-merge (§9.4). TypeScript et ESLint ne detectent pas les erreurs SQL — seul PostgreSQL les signale a l'execution (cf. learning PD-55 : "pas de subquery dans les index partiels").
• Attention INV-177-20 : la migration PD-177 ne doit PAS utiliser d'index partiel avec syntaxe non supportee. L'ajout de colonne signer_address est une operation simple (ALTER TABLE ADD COLUMN).
• Immutabilite append-only (INV-177-13/14) : protegee au niveau applicatif (AnchorBatchService refuse UPDATE/DELETE sur batches FINALIZED). La protection WORM au niveau base est hors perimetre PD-177 (definie dans la spec §3).

6.5 BullMQ¶

• Version : bullmq@^5.1.0 avec @nestjs/bullmq@11.0.4
• INV-177-21 : le code existant PD-55 utilise deja getJobSchedulers() / removeJobScheduler() (non deprecie). PD-177 ne doit pas introduire getRepeatableJobs / removeRepeatableByKey.
• Le processor BlockchainAnchorProcessor utilise @Processor('anchor') et WorkerHost — pas de changement d'API.

7. Securite¶

7.1 Modele de menace PD-177¶

7.2 Mecanisme anti-fuite (SecretLeakInterceptor — N-02)¶

Architecture :

[Service output] → SecretLeakInterceptor → [Channel (log/API/trace)]
                          |
                          ├── Pattern match? → BLOCK + throw BlockchainError(SECRET_LEAK_DETECTED)
                          │                   + AuditService.logEvent('SECURITY_INCIDENT', ...)
                          │
                          └── No match → PASS

Patterns detectes (extension de BlockchainError.sanitizeContext()) : - Cle privee hex : /^0x[a-fA-F0-9]{64}$/ - Mnemonic : /^([a-z]+\s){11,23}[a-z]+$/ - Keywords : /mnemonic|seed|private.?key|secret|password/i - KMS key material : /^[A-Za-z0-9+/]{43,}={0,2}$/ (base64 >= 32 bytes)

Points d'application : 1. NestJS Interceptor global sur les controllers blockchain 2. Logger wrapper pour les services blockchain (override de Logger.log/error/warn) 3. BlockchainError.context (existant, PD-52)

7.3 Fail-closed (INV-177-09)¶

Le comportement fail-closed est garanti par un NestJS Response Interceptor qui scanne l'Observable apres next.handle() via un operateur RxJS tap :

intercept(context, next): Observable<any> {
  return next.handle().pipe(
    tap(data => this.scanForSecrets(data)),   // scan la reponse AVANT serialisation HTTP
    catchError(err => {                        // scan aussi les erreurs
      this.scanForSecrets(err);
      throw err;
    })
  );
}

Sequence d'execution : 1. La requete traverse le handler NestJS normalement (next.handle()) 2. L'Observable retourne par le handler est pipe avec un operateur tap qui scanne le contenu 3. Si un pattern secret est detecte dans data (reponse) ou err (erreur) : a. throw new BlockchainError(SECRET_LEAK_DETECTED) — bloque la serialisation HTTP (NestJS n'envoie pas la reponse originale) b. AuditService.logEvent('SECURITY_INCIDENT', ...) — cree l'incident securite de maniere synchrone 4. Le throw est lui-meme sanitize (le BlockchainError ne contient pas le secret) 5. Si aucun pattern detecte, la reponse est transmise normalement au client

Pourquoi fail-closed : Le scan se fait dans le pipe RxJS avant que NestJS ne serialise la reponse HTTP vers le client. Si un secret est detecte, l'exception remplace la reponse originale — le canal HTTP ne recoit jamais le contenu sensible. Pour les logs, le Logger wrapper applique le meme scan de maniere synchrone avant console.log().

8. Hypotheses d'implementation¶

9. Points de vigilance¶

9.1 Risques techniques¶

9.2 Points de coordination inter-equipes¶

9.3 Non-regression PD-52/PD-55¶

Les modifications PD-177 ne doivent pas casser les tests existants PD-52 et PD-55. Verification :

1. Les codes d'erreur ajoutes sont des nouvelles entrees dans l'enum, pas des renames
2. La colonne signer_address est nullable donc les batches existants restent valides
3. Le ConfirmationTracker garde le meme comportement par defaut (la politique de confirmation utilise les valeurs de config existantes par defaut)
4. Le TransactionResult DTO ajoute un champ optionnel signerAddress?
5. Le ProofArtifactDto ajoute un champ optionnel blockchain?
6. L'export de CustodyService depuis BlockchainModule est additif

9.4 Checklist pre-merge¶

• npm run migration:validate — zero erreur
• npm run migration:run — migration appliquee avec succes
• npm test — tous les tests PD-52 et PD-55 passent (non-regression)
• npm run test:e2e — tests E2E passent
• Grep getRepeatableJobs|removeRepeatableByKey dans les fichiers PD-177 → zero match
• Grep private.?key|mnemonic|seed dans les DTOs et reponses API PD-177 → zero match
• Grep crypto\.randomUUID dans les fichiers PD-177 generant des UUID → present
• Grep pv-test- dans les fixtures de test PD-177 → toutes les cles ephemeres prefixees
• Le runbook wallet-recovery-procedure.md existe et est versionne
• Coverage >= 85% sur les fichiers PD-177

Annexe A : Detail des fichiers modifies/crees¶

Fichiers modifies¶

Fichiers crees¶

Annexe B : Mapping complet Tests → Composants¶