PD-275 — Plan d'implémentation¶

1. Découpage en composants¶

C1 — Migration DDL (migration-pd275)¶

Responsabilité : Ajouter la colonne confirmation_count sur anchor_batches et créer la table signer_registry dans le schéma vault_blockchain.

Fichiers : - src/database/migrations/XXXXXXXXX-pd275-finality-signer.ts

Détails : - anchor_batches.confirmation_count : INTEGER NOT NULL DEFAULT 0, CHECK >= 0 AND <= 2147483647 - Table vault_blockchain.signer_registry : - address VARCHAR(42) PRIMARY KEY (EIP-55) - status VARCHAR(10) NOT NULL DEFAULT 'ACTIVE' CHECK IN ('ACTIVE', 'REVOKED') - revoked_at TIMESTAMPTZ NULL - revoked_by VARCHAR(255) NULL - created_at TIMESTAMPTZ NOT NULL DEFAULT NOW() - updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() - Index : idx_signer_registry_status sur (status) - Migration down : DROP signer_registry, DROP COLUMN confirmation_count

C2 — Entity SignerRegistry (signer-registry-entity)¶

Responsabilité : Entité TypeORM pour le registre des signers autorisés.

Fichiers : - src/modules/anchor/entities/signer-registry.entity.ts

Détails : - Schéma : vault_blockchain - Table : signer_registry - Enum : SignerStatus (ACTIVE, REVOKED) dans src/modules/anchor/enums/signer-status.enum.ts - Colonnes mappées : address, status, revokedAt, revokedBy, createdAt, updatedAt

C3 — Extension Entity AnchorBatch (anchor-batch-extension)¶

Responsabilité : Ajouter la colonne confirmation_count à l'entité existante AnchorBatch.

Fichiers : - src/modules/anchor/entities/anchor-batch.entity.ts (modification)

Détails : - Nouveau champ : @Column({ type: 'int', name: 'confirmation_count', default: 0 }) confirmationCount!: number;

C4 — Service SignerRegistryService (signer-registry-service)¶

Responsabilité : CRUD et logique métier du registre des signers. Centralise les gardes signer (isActive, revoke) avec verrouillage pessimiste.

Fichiers : - src/modules/anchor/services/signer-registry.service.ts

Méthodes : - findByAddress(address: string, manager?: EntityManager): Promise<SignerRegistry | null> — lecture simple - findByAddressForUpdate(address: string, manager: EntityManager): Promise<SignerRegistry | null> — SELECT ... FOR UPDATE - assertSignerActive(address: string, manager: EntityManager): Promise<void> — fail-closed, throws ERR-SIGNER-REVOKED ou ERR-SIGNER-NOT-FOUND - revokeSigner(address: string, actorIdentity: string, actorRoles: string[], manager: EntityManager): Promise<SignerRegistry> — transition atomique ACTIVE -> REVOKED + audit trail. Correction v2 (MAJ-02) : Le service vérifie que actorRoles contient ADMIN ou SIGNER_ADMIN — throws ERR-REVOKE-UNAUTHORIZED si non autorisé. Double protection : controller (@Roles) + service (assertion interne) pour couvrir les appels service-to-service.

C5 — Service FinalityGuardService (finality-guard-service)¶

Responsabilité : Centralise la logique de garde de finalité (confirmation_count >= FINALITY_DEPTH).

Fichiers : - src/modules/anchor/services/finality-guard.service.ts

Méthodes : - assertFinalityReached(batch: AnchorBatch): void — throws ERR-FINALITY-INSUFFICIENT si confirmation_count < FINALITY_DEPTH - updateConfirmationCount(batchId: string, count: number): Promise<void> — valide bornes [0, 2147483647], persiste

Configuration : - FINALITY_DEPTH lu depuis ConfigService (anchor.finalityDepth), valeur par défaut configurable par environnement

C6 — Modification AnchorBatchService (anchor-batch-service-extension)¶

Responsabilité : Intégrer les gardes de finalité et de signer dans les flux existants finalizeBatch() et submitBatch().

Fichiers : - src/modules/anchor/services/anchor-batch.service.ts (modification)

Modifications : - finalizeBatch() : avant la transition PENDING_FINALITY -> FINALIZED, appeler FinalityGuardService.assertFinalityReached(batch). Le confirmation_count est déjà persisté par C5. - submitBatch() : dans la même transaction, appeler SignerRegistryService.assertSignerActive(signerAddress, manager) avec SELECT ... FOR UPDATE avant d'autoriser la soumission. - Les deux méthodes conservent leur transaction existante et ajoutent les gardes dans le scope transactionnel.

C7 — Controller SignerController (signer-controller)¶

Responsabilité : Exposer l'endpoint REST POST /anchor/signers/:address/revoke pour la révocation.

Fichiers : - src/modules/anchor/controllers/signer.controller.ts - src/modules/anchor/dto/revoke-signer.dto.ts

Détails : - Guard : OidcJwtAuthGuard + @Roles('ADMIN', 'SIGNER_ADMIN') (au moins un des deux rôles) - Extraction actorIdentity depuis request.user.sub (JWT claim, jamais du payload) - Validation anti-spoofing : si le body contient un champ revokedBy, retourner ERR-REVOKEDBY-SPOOFING (400 Bad Request) - Appel transactionnel à SignerRegistryService.revokeSigner(address, actorIdentity, manager) - Audit event : SIGNER_REVOKED - Réponses : 200 (succès), 400 (spoofing), 403 (unauthorized), 404 (not found), 409 (already revoked)

C8 — Guard SignerActiveGuard (SUPPRIMÉ — correction v2)¶

Correction v2 (MAJ-01/MAJ-03) : Le guard NestJS HTTP SignerActiveGuard est supprimé du plan. Le contrôle signer est effectué exclusivement dans le service layer (SignerRegistryService.assertSignerActive()) avec SELECT ... FOR UPDATE transactionnel, conformément à INV-275-11. Le flux principal passe par un worker BullMQ (pas une route HTTP), rendant un guard HTTP non pertinent. Un guard HTTP serait un pré-contrôle sans transaction, créant un risque TOCTOU contradictoire avec la sérialisation contractuelle.

C9 — Audit Events Extension (audit-events-extension)¶

Responsabilité : Enrichir le registre d'audit avec les événements PD-275.

Fichiers : - src/modules/audit/types/audit-action.types.ts (modification)

Nouveaux événements : - SIGNER_REVOKED — après revocation réussie - SIGNER_REVOKE_DENIED — après refus de revocation (unauthorized, already revoked) - FINALITY_CHECK_FAILED — après refus de finalisation pour confirmation insuffisante - CONFIRMATION_COUNT_UPDATED — après mise à jour du compteur

C10 — Error Codes Extension (error-codes-extension)¶

Responsabilité : Ajouter les codes d'erreur PD-275 au registre existant.

Fichiers : - src/modules/anchor/constants/error-codes.ts (nouveau ou extension de src/modules/blockchain/constants/error-codes.ts)

Codes : - ERR-FINALITY-INSUFFICIENT - ERR-CONFIRMATION-COUNT-INVALID - ERR-SIGNER-NOT-FOUND - ERR-SIGNER-REVOKED - ERR-SIGNER-ALREADY-REVOKED - ERR-AUDIT-TRAIL-MISSING - ERR-REVOKE-UNAUTHORIZED - ERR-REVOKEDBY-SPOOFING

C11 — Module Registration (module-registration)¶

Responsabilité : Enregistrer les nouveaux services, entités, controllers et guards dans AnchorModule.

Fichiers : - src/modules/anchor/anchor.module.ts (modification)

Détails : - TypeOrmModule.forFeature([..., SignerRegistry]) - Providers : SignerRegistryService, FinalityGuardService - Controllers : SignerController

2. Flux techniques¶

FT1 — Mise à jour du compteur de confirmations¶

ConfirmationTracker.track(network, txHash)
  │
  ├─ poll RPC → confirmations = N
  │
  └─ FinalityGuardService.updateConfirmationCount(batchId, N)
       │
       ├─ Valider N ∈ [0, 2147483647] → sinon throw ERR-CONFIRMATION-COUNT-INVALID
       │
       ├─ UPDATE anchor_batches SET confirmation_count = N WHERE batch_id = :id
       │
       └─ AuditService.logEvent('CONFIRMATION_COUNT_UPDATED', SYSTEM_USER_ID, batchId, { count: N })

FT2 — Finalisation avec garde de finalité¶

AnchorBatchService.finalizeBatch(batchId, txResult)
  │
  ├─ queryRunner.startTransaction()
  │
  ├─ SELECT * FROM anchor_batches WHERE batch_id = :id FOR UPDATE
  │
  ├─ FinalityGuardService.assertFinalityReached(batch)
  │    └─ IF batch.confirmationCount < FINALITY_DEPTH
  │         → throw BlockchainError(ERR-FINALITY-INSUFFICIENT)
  │         → AuditService.logEvent('FINALITY_CHECK_FAILED')
  │
  ├─ isValidAnchorStatusTransition(batch.status, FINALIZED) → true
  │
  ├─ batch.status = FINALIZED, batch.finalizedAt = now()
  │
  ├─ queryRunner.manager.save(batch)
  │
  ├─ queryRunner.commitTransaction()
  │
  └─ AuditService.logEvent('ANCHOR_BATCH_FINALIZED', ...)

FT3 — Révocation d'un signer¶

POST /anchor/signers/:address/revoke
  │
  ├─ OidcJwtAuthGuard → vérifie JWT valide
  │
  ├─ RolesGuard → vérifie role ∈ {ADMIN, SIGNER_ADMIN}
  │    └─ Si non → 403 ERR-REVOKE-UNAUTHORIZED
  │
  ├─ Validation DTO : si body contient 'revokedBy' → 400 ERR-REVOKEDBY-SPOOFING
  │
  ├─ actorIdentity = request.user.sub  (JWT claim)
  │
  ├─ dataSource.transaction(async (manager) => {
  │     │
  │     ├─ SELECT * FROM signer_registry WHERE address = :addr FOR UPDATE
  │     │    └─ null → throw ERR-SIGNER-NOT-FOUND (404)
  │     │
  │     ├─ IF signer.status === 'REVOKED'
  │     │    └─ throw ERR-SIGNER-ALREADY-REVOKED (409)
  │     │
  │     ├─ signer.status = 'REVOKED'
  │     ├─ signer.revokedAt = now()
  │     ├─ signer.revokedBy = actorIdentity
  │     │
  │     ├─ manager.save(signer)
  │     │    └─ Si échec persistance revokedAt/revokedBy → ERR-AUDIT-TRAIL-MISSING (rollback)
  │     │
  │     └─ AuditService.logEvent('SIGNER_REVOKED', actorIdentity, address, { ... })
  │   })
  │
  └─ 200 { address, status: 'REVOKED', revokedAt, revokedBy }

FT4 — Soumission avec garde signer actif¶

Correction v2 (BLK-01) : Le contrôle signer DOIT précéder createBatch() et buildBatch() pour garantir CA-05 ("aucun batch créé" si signer REVOKED/inconnu). Le contrôle est déplacé au début du processor, dans une transaction dédiée.

BlockchainAnchorProcessor.process(job)
  │
  ├─ [AJOUTÉ] Résolution signerAddress (via WalletService.getAddress() — PD-177)
  │
  ├─ [AJOUTÉ] SignerRegistryService.assertSignerActive(signerAddress, manager)
  │     │     avec SELECT ... FOR UPDATE dans transaction dédiée
  │     │     ├─ null → throw ERR-SIGNER-NOT-FOUND (fail-closed) — STOP, aucun batch créé
  │     │     └─ status === 'REVOKED' → throw ERR-SIGNER-REVOKED (fail-closed) — STOP, aucun batch créé
  │
  ├─ AnchorBatchService.createBatch(...)  (existant, exécuté seulement si signer ACTIVE)
  │
  ├─ AnchorBatchService.buildBatch(...)   (existant)
  │
  ├─ AnchorBatchService.submitBatch(batch)  [MODIFIÉ]
  │     │
  │     ├─ queryRunner.startTransaction()
  │     │
  │     ├─ [AJOUTÉ] Re-vérification signer ACTIVE avec SELECT ... FOR UPDATE (double-check transactionnel)
  │     │    ├─ null → throw ERR-SIGNER-NOT-FOUND (fail-closed)
  │     │    └─ status === 'REVOKED' → throw ERR-SIGNER-REVOKED (fail-closed, révoqué entre createBatch et submit)
  │     │
  │     ├─ ... suite du flux submit existant dans la même transaction ...
  │     │
  │     └─ queryRunner.commitTransaction()
  │
  ├─ BlockchainAdapterService.waitForConfirmation(...)  (existant)
  │     │
  │     └─ FinalityGuardService.updateConfirmationCount(batchId, N) [NOUVEAU]
  │
  └─ AnchorBatchService.finalizeBatch(batch, txResult) [MODIFIÉ avec garde finalité]

2bis. Diagrammes Mermaid¶

Graphe de dépendances entre composants¶

graph TD
    C1["C1 — Migration DDL"]
    C2["C2 — Entity SignerRegistry"]
    C3["C3 — Extension Entity AnchorBatch"]
    C4["C4 — SignerRegistryService"]
    C5["C5 — FinalityGuardService"]
    C6["C6 — Modification AnchorBatchService"]
    C7["C7 — SignerController"]
    C9["C9 — Audit Events Extension"]
    C10["C10 — Error Codes Extension"]
    C11["C11 — Module Registration"]

    C2 -->|entity table| C1
    C3 -->|colonne confirmation_count| C1
    C4 -->|entity| C2
    C4 -->|codes erreur| C10
    C4 -->|audit events| C9
    C5 -->|entity| C3
    C5 -->|codes erreur| C10
    C5 -->|audit events| C9
    C6 -->|garde finalité| C5
    C6 -->|garde signer| C4
    C7 -->|service revocation| C4
    C7 -->|codes erreur| C10
    C11 -->|enregistre| C2
    C11 -->|enregistre| C4
    C11 -->|enregistre| C5
    C11 -->|enregistre| C7

    style C1 fill:#e8f4fd,stroke:#2196F3
    style C6 fill:#fff3e0,stroke:#FF9800
    style C7 fill:#fff3e0,stroke:#FF9800
    style C11 fill:#f3e5f5,stroke:#9C27B0

Diagramme de séquence — Soumission avec gardes signer + finalité (FT4)¶

sequenceDiagram
    participant BullMQ as BlockchainAnchorProcessor
    participant Wallet as WalletService (PD-177)
    participant Signer as SignerRegistryService
    participant Batch as AnchorBatchService
    participant Finality as FinalityGuardService
    participant Adapter as BlockchainAdapterService
    participant Audit as AuditService
    participant DB as PostgreSQL

    BullMQ->>Wallet: getAddress()
    Wallet-->>BullMQ: signerAddress

    Note over BullMQ,DB: Transaction dédiée — garde signer pré-création
    BullMQ->>Signer: assertSignerActive(signerAddress, manager)
    Signer->>DB: SELECT ... FOR UPDATE signer_registry
    alt Signer ACTIVE
        DB-->>Signer: signer (status=ACTIVE)
        Signer-->>BullMQ: OK
    else Signer REVOKED ou absent
        DB-->>Signer: signer (status=REVOKED) / null
        Signer-->>BullMQ: throw ERR-SIGNER-REVOKED / ERR-SIGNER-NOT-FOUND
        Note over BullMQ: STOP — aucun batch créé
    end

    BullMQ->>Batch: createBatch(...)
    BullMQ->>Batch: buildBatch(...)

    Note over BullMQ,DB: Transaction submit — double-check signer
    BullMQ->>Batch: submitBatch(batch)
    Batch->>Signer: assertSignerActive(signerAddress, manager)
    Signer->>DB: SELECT ... FOR UPDATE (re-vérification)
    alt Signer toujours ACTIVE
        Signer-->>Batch: OK
        Batch->>DB: UPDATE batch status → SUBMITTED
        Batch->>DB: COMMIT
    else Signer révoqué entre-temps
        Signer-->>Batch: throw ERR-SIGNER-REVOKED
        Batch->>DB: ROLLBACK
    end

    BullMQ->>Adapter: waitForConfirmation(txHash)
    Adapter-->>BullMQ: confirmations = N

    BullMQ->>Finality: updateConfirmationCount(batchId, N)
    Finality->>DB: UPDATE anchor_batches SET confirmation_count = N
    Finality->>Audit: logEvent(CONFIRMATION_COUNT_UPDATED)

    BullMQ->>Batch: finalizeBatch(batch, txResult)
    Batch->>DB: SELECT ... FOR UPDATE anchor_batches
    Batch->>Finality: assertFinalityReached(batch)
    alt confirmation_count >= FINALITY_DEPTH
        Finality-->>Batch: OK
        Batch->>DB: UPDATE status → FINALIZED
        Batch->>DB: COMMIT
        Batch->>Audit: logEvent(ANCHOR_BATCH_FINALIZED)
    else confirmation_count < FINALITY_DEPTH
        Finality->>Audit: logEvent(FINALITY_CHECK_FAILED)
        Finality-->>Batch: throw ERR-FINALITY-INSUFFICIENT
        Batch->>DB: ROLLBACK
    end

Diagramme de séquence — Révocation d'un signer (FT3)¶

sequenceDiagram
    participant Client as Client HTTP
    participant Guard as OidcJwtAuthGuard + RolesGuard
    participant Ctrl as SignerController (C7)
    participant Svc as SignerRegistryService (C4)
    participant Audit as AuditService
    participant DB as PostgreSQL

    Client->>Guard: POST /anchor/signers/:address/revoke
    Guard->>Guard: Vérifier JWT + rôle ∈ {ADMIN, SIGNER_ADMIN}
    alt Rôle non autorisé
        Guard-->>Client: 403 ERR-REVOKE-UNAUTHORIZED
    end

    Guard-->>Ctrl: request (user.sub = actorIdentity)
    Ctrl->>Ctrl: Vérifier body ne contient pas 'revokedBy'
    alt Body contient revokedBy
        Ctrl-->>Client: 400 ERR-REVOKEDBY-SPOOFING
    end

    Note over Ctrl,DB: Transaction atomique
    Ctrl->>Svc: revokeSigner(address, actorIdentity, actorRoles, manager)
    Svc->>DB: SELECT ... FOR UPDATE signer_registry WHERE address = :addr
    alt Signer absent
        DB-->>Svc: null
        Svc->>Audit: logEvent(SIGNER_REVOKE_DENIED)
        Svc-->>Ctrl: throw ERR-SIGNER-NOT-FOUND
        Ctrl-->>Client: 404
    else Signer déjà REVOKED
        DB-->>Svc: signer (status=REVOKED)
        Svc->>Audit: logEvent(SIGNER_REVOKE_DENIED)
        Svc-->>Ctrl: throw ERR-SIGNER-ALREADY-REVOKED
        Ctrl-->>Client: 409
    else Signer ACTIVE
        Svc->>DB: UPDATE status=REVOKED, revokedAt=now(), revokedBy=actorIdentity
        Svc->>Audit: logEvent(SIGNER_REVOKED)
        Svc-->>Ctrl: signer (revoked)
        Ctrl-->>Client: 200 { address, status, revokedAt, revokedBy }
    end

3. Mapping invariants → mécanismes¶

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

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

6. Gestion des erreurs¶

Stratégie de propagation : Toutes les erreurs métier sont des exceptions NestJS typées (BadRequestException, ForbiddenException, NotFoundException, ConflictException) avec un payload structuré { code: 'ERR-*', message: string }. Les erreurs internes (worker BullMQ) sont loguées via Logger et le batch passe à FAILED via failBatch().

7. Impacts sécurité¶

7.1 Contrôle d'accès¶

• Endpoint POST /anchor/signers/:address/revoke : protégé par OidcJwtAuthGuard + @Roles('ADMIN', 'SIGNER_ADMIN').
• Le rôle SIGNER_ADMIN est un nouveau rôle à créer dans Keycloak. Si ce rôle n'existe pas encore, il doit être provisionné avant déploiement.
• Les endpoints existants (GET /anchor/batches/:id/proof) ne sont pas modifiés.

7.2 Anti-usurpation audit trail¶

• revokedBy est toujours extrait de request.user.sub (JWT claim).
• Le DTO de revocation ne contient pas de champ revokedBy. Si un champ revokedBy est détecté dans le body (via validation explicite), la requête est rejetée avec ERR-REVOKEDBY-SPOOFING.
• Aucun header métier ne peut injecter revokedBy.

7.3 Concurrence et intégrité¶

• SELECT ... FOR UPDATE sur signer_registry sérialise les accès concurrents.
• La politique de timeout transactionnel PostgreSQL standard s'applique (fail-closed en cas de deadlock).
• Aucun double audit trail possible grâce au verrou pessimiste.

7.4 Journalisation¶

• Tous les événements de sécurité (revocation, refus, spoofing) sont audités via AuditService.
• Les traces incluent actorIdentity, address, timestamp, result (success/denied).

8. Hypothèses techniques¶

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

9.1 Seed initial du registre signer (HD-03 / Q-05)¶

Risque critique : Si le registre signer_registry est vide au déploiement, le guard fail-closed bloquera toute soumission de batch. L'ensemble du flux d'ancrage sera indisponible.

Mitigation : Inclure un script de seed (seed-signers.ts) ou une insertion SQL dans la migration up pour les adresses connues (wallet actif de production). Documenter la procédure de seed dans la documentation opérationnelle.

9.2 Valeur de FINALITY_DEPTH (Q-01)¶

Risque : Sans valeur validée par environnement, les tests TC-NOM-02/TC-NOM-03 sont exécutables en paramétrique mais la conformité numérique n'est pas garantie en production.

Mitigation : Utiliser une valeur configurable avec un défaut conservateur (ex: 12 pour Polygon, aligné sur NETWORK_CONFIRMATION_POLICY.polygon.confirmations). Documenter Q-01 comme décision à finaliser.

9.3 Interaction finalizeBatch() existant vs nouvelle garde¶

Piège : Le finalizeBatch() actuel (PD-55) fait déjà un lock: { mode: 'pessimistic_write' } et valide la transition d'état. La garde de finalité doit s'insérer après l'acquisition du verrou et avant la mutation d'état, dans la même transaction.

Vérification : Pas de code-path qui contourne la garde (pas de finalizeBatch alternatif sans vérification).

9.4 Normalisation des adresses signer (Q-03)¶

Risque : Si les adresses ne sont pas normalisées (EIP-55), une même adresse en minuscules et en checksum pourrait créer deux entrées distinctes dans signer_registry.

Mitigation : Normalisation EIP-55 systématique à l'insertion (getAddress() d'ethers.js) et à la requête dans SignerRegistryService. La clé primaire est l'adresse normalisée.

9.5 Tests de concurrence (TC-NOM-10, TC-NOM-11)¶

Piège : Les tests de concurrence nécessitent un vrai PostgreSQL (pas de mock). Utiliser DataSource.transaction() avec deux connexions parallèles pour prouver la sérialisation.

Pattern recommandé : Test d'intégration avec deux Promise.all([revokePromise, submitPromise]) sur un environnement de test PostgreSQL.

9.6 Aucune modification d'autres modules¶

Aucune modification d'autres modules (documents, crypto, etc.) n'est nécessaire pour PD-275. Les changements sont confinés au module anchor et à ses dépendances directes (audit, blockchain/constants).

10. Hors périmètre¶

• Rotation automatique des signers — hors scope PD-275
• Réactivation d'un signer REVOKED — hors scope (état terminal, INV-275-06)
• Multi-signature — hors scope PD-275
• UI/API d'administration complète des signers — seul l'endpoint de revocation est dans le scope
• Modification des modèles TLA+ et Alloy — validés en amont
• Toute dérogation fail-open — interdit par INV-275-01
• Mécanisme de mise à jour de confirmation_count (interface exacte du polling) — le ConfirmationTracker existant (PD-52/PD-177) fournit déjà les confirmations ; PD-275 ajoute uniquement la persistance et la garde
• Machine à états batch complète — PD-275 contractualise uniquement PENDING_FINALITY -> FINALIZED et FINALIZED -> * : INTERDITE ; le modèle complet est traité par Q-02
• Gestion des deadlocks PostgreSQL avancée — la politique standard du serveur s'applique (H-07)