PD-277 — Spécification canonique anti-rejeu nonce et PKI certificate binding (v2)¶

1. Objectif¶

La User Story PD-277 impose la mise en conformité du module legal-pre pour supprimer les 2 non-conformités bloquantes restantes de l’audit formel PV PRE, en ajoutant des garanties contractuelles de: - non-réutilisation de nonce lors de reEncrypt(); - liaison cryptographique explicite entre un LegalReKey et les certificats PKI des deux parties; - traçabilité de conformité via régénération des faits Prolog et revalidation complète de l’audit (24 checks).

Objectif de résultat: 24/24 checks BLOQUANTS à l’état OK.

2. Périmètre / Hors périmètre¶

Inclus¶

• Extension contractuelle du modèle LegalReKey pour porter:
• historique des nonces utilisés (used_nonces);
• identifiant de certificat propriétaire (owner_certificate_id);
• identifiant de certificat destinataire (recipient_certificate_id).
• Contrôle anti-rejeu sur le flux métier reEncrypt().
• Contrôle de binding PKI sur le flux métier generateReKey().
• Transactionnalité atomique entre vérification nonce, insertion nonce et re-chiffrement.
• Régénération de _generated-facts.pl alignée sur les nouveaux attributs contractuels.
• Couverture de tests unitaires et d’intégration des deux mécanismes.
• Vérification de non-régression sur les 22 checks déjà conformes.
• Vérification explicite qu’aucun nouvel état métier (StatusEnum) n’est introduit pour les entités Legal*.

Exclu¶

• Les 5 checks de complétude non bloquants (cron destruction, cron expiration, ETSI trusted list, blockchain anchoring, revocation propagation).
• Toute modification du service PRE bas niveau (pre.service.ts, umbral.provider.ts).
• Toute évolution fonctionnelle hors module legal-pre.

3. Définitions¶

• LegalReKey: artefact métier représentant une clé de re-chiffrement légale.
• Nonce: valeur unique fournie par requête pour prévenir le rejeu.
• Anti-rejeu: rejet d’une opération si le nonce a déjà été utilisé dans le périmètre défini.
• PKI certificate binding: contrainte liant un LegalReKey aux certificats des parties (owner/recipient).
• Fail-closed: en cas d’erreur de validation, l’opération est refusée.
• Check bloquant: règle d’audit dont l’échec rend la conformité invalide.
• Audit Prolog: exécution de référence run_audit. sur les faits générés.

4. Format du nonce (contractuel)¶

• Longueur et forme: UUID v4 strict, 36 caractères, format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx.
• Encodage: ASCII lowercase uniquement.
• Génération: crypto.randomUUID() côté serveur uniquement, jamais côté client.
• Normalisation: aucune normalisation appliquée (le format UUID v4 lowercase est canonique).
• Validation: tout nonce hors format contractuel est rejeté en fail-closed avant traitement crypto.

5. Invariants (non négociables)¶

6. Contrat de persistance et DDL¶

Politique used_nonces¶

• used_nonces est un array JSONB rattaché à chaque LegalReKey.
• TTL des entrées used_nonces = durée de vie du LegalReKey.
• Aucune purge séparée des nonces.
• À la destruction du LegalReKey, les nonces sont détruits avec l’entité.

DDL contractuel¶

used_nonces JSONB NOT NULL DEFAULT '[]'::jsonb
owner_certificate_id VARCHAR(255) NOT NULL
recipient_certificate_id VARCHAR(255) NOT NULL

Immuabilité certificats¶

• owner_certificate_id et recipient_certificate_id sont écrits à la création.
• Toute tentative de modification ultérieure est rejetée en fail-closed.

7. Atomicité et concurrence¶

Pour reEncrypt, les opérations suivantes sont exécutées de manière atomique: 1. vérification que le nonce est inédit pour le LegalReKey; 2. insertion du nonce dans used_nonces; 3. re-chiffrement.

Contrat technique: - transaction PostgreSQL avec isolation SERIALIZABLE, ou - verrouillage applicatif équivalent (advisory lock) scope LegalReKey, - et rollback complet si une étape échoue.

Aucun succès métier n’est retourné si l’une des 3 étapes échoue.

8. Faits Prolog attendus (canonique)¶

% CHECK 23 — Anti-rejeu nonce
entity_column(legal_re_key, used_nonces, jsonb).

% CHECK 24 — PKI Certificate Binding
entity_column(legal_re_key, owner_certificate_id, varchar).
entity_column(legal_re_key, recipient_certificate_id, varchar).

Ces faits sont obligatoires dans _generated-facts.pl avant exécution de run_audit..

9. Flux nominaux¶

Flux F1 — Génération de ReKey avec binding PKI¶

1. Le système reçoit une demande generateReKey.
2. Le système résout l’identité owner et recipient selon le mandat valide.
3. Le système vérifie l’existence et la validité des certificats PKI requis pour les deux parties.
4. Le système lie contractuellement owner_certificate_id et recipient_certificate_id au LegalReKey.
5. Le système persiste le LegalReKey avec ces liaisons.
6. Le système retourne un succès uniquement si toutes les validations sont satisfaites.

Résultat attendu: tout LegalReKey nouvellement créé est lié à un couple de certificats valide et immuable.

Flux F2 — Re-chiffrement avec anti-rejeu nonce¶

1. Le système reçoit une demande reEncrypt contenant un nonce.
2. Le système valide le nonce selon le contrat UUID v4 lowercase ASCII.
3. Le système exécute atomiquement la vérification nonce inédit + insertion nonce + re-chiffrement.
4. Le système retourne un succès uniquement après commit.

Résultat attendu: la première utilisation d’un nonce valide est acceptée, toute réutilisation est rejetée.

Flux F3 — Régénération des faits de conformité¶

1. Les faits _generated-facts.pl sont régénérés à partir de l’état de code et de schéma en vigueur.
2. Les faits incluent explicitement les faits canoniques CHECK 23 et CHECK 24.
3. L’audit Prolog est exécuté sur ces faits.

Résultat attendu: alignement complet entre artefacts de conformité et comportement contractuel.

Flux F4 — Validation globale de conformité¶

1. Exécution de la suite de tests ciblés PD-277.
2. Exécution de l’audit Prolog complet.
3. Vérification de non-régression des checks déjà conformes.
4. Vérification explicite d’absence de nouveaux StatusEnum sur entités Legal*.

Résultat attendu: 24/24 checks bloquants à OK sans nouvelle transition métier.

Stratégie migration DDL (obligatoire)¶

• Modification de colonne existante: non.
• Ajouts de colonnes: oui (used_nonces, owner_certificate_id, recipient_certificate_id).
• Backfill: non requis si migration atomique et contraintes respectées.
• Down migration: exigée (suppression propre des colonnes ajoutées + restauration du schéma initial).
• Contraintes ajoutées: NOT NULL + defaults contractuels définis dans cette spécification.
• Impact triggers/workers dépendants: vérification obligatoire avant clôture.

9bis. Diagrammes Mermaid¶

Diagramme d’état — Cycle de vie d’un nonce dans le périmètre d’un LegalReKey¶

Référence : INV-277-02 (unicité nonce), INV-277-03 (persistance avant succès), INV-277-01 (fail-closed)

stateDiagram-v2
    [*] --> Reçu : reEncrypt(nonce)
    Reçu --> Rejeté_Format : Format non UUID v4 lowercase\n[INV-277-01 fail-closed]
    Reçu --> Validé_Format : Format UUID v4 conforme
    Validé_Format --> Rejeté_Rejeu : Nonce déjà dans used_nonces\n[INV-277-02 nonce-unique]
    Validé_Format --> Persisté : Insertion atomique dans used_nonces\n[INV-277-03 persist-before-success]
    Persisté --> Succès : Commit transaction + retour succès
    Persisté --> Rollback : Échec re-chiffrement\n[INV-277-01 fail-closed]
    Rollback --> [*]
    Rejeté_Format --> [*]
    Rejeté_Rejeu --> [*]
    Succès --> [*]

Diagramme de séquence — F1 : Génération de ReKey avec binding PKI¶

Référence : INV-277-04 (binding obligatoire), INV-277-05 (immuabilité), INV-277-01 (fail-closed)

sequenceDiagram
    participant Client
    participant LegalPreService
    participant MandateValidator
    participant PKI as PKI Certificate Store
    participant DB as PostgreSQL

    Client->>LegalPreService: generateReKey(mandateId)
    LegalPreService->>MandateValidator: validateMandate(mandateId)
    MandateValidator-->>LegalPreService: {ownerId, recipientId}

    LegalPreService->>PKI: getCertificate(ownerId)
    PKI-->>LegalPreService: ownerCertificate

    LegalPreService->>PKI: getCertificate(recipientId)
    PKI-->>LegalPreService: recipientCertificate

    alt Certificat owner ou recipient absent/invalide [INV-277-04]
        LegalPreService-->>Client: PRE_CERTIFICATE_BINDING_FAILED [INV-277-01]
    else Certificats valides
        LegalPreService->>DB: INSERT LegalReKey (owner_certificate_id, recipient_certificate_id, used_nonces=[])
        Note over DB: Binding immuable après création [INV-277-05]
        DB-->>LegalPreService: OK
        LegalPreService-->>Client: LegalReKey créé avec binding PKI
    end

Diagramme de séquence — F2 : Re-chiffrement avec anti-rejeu nonce (transaction atomique)¶

Référence : INV-277-02 (unicité nonce), INV-277-03 (persistance avant succès), INV-277-01 (fail-closed), INV-277-06 (chiffrement at-rest)

sequenceDiagram
    participant Client
    participant LegalPreService
    participant DB as PostgreSQL (SERIALIZABLE)
    participant PRE as Module PRE (re-chiffrement)

    Client->>LegalPreService: reEncrypt(reKeyId, nonce, payload)

    LegalPreService->>LegalPreService: Valider format nonce UUID v4 lowercase ASCII
    alt Format invalide [INV-277-01]
        LegalPreService-->>Client: ERR-NONCE-FORMAT (fail-closed)
    end

    rect rgb(240, 248, 255)
        Note over LegalPreService,DB: Transaction atomique SERIALIZABLE
        LegalPreService->>DB: BEGIN SERIALIZABLE
        LegalPreService->>DB: SELECT used_nonces FROM legal_re_key WHERE id = reKeyId FOR UPDATE
        DB-->>LegalPreService: used_nonces[]

        alt Nonce déjà dans used_nonces [INV-277-02]
            LegalPreService->>DB: ROLLBACK
            LegalPreService-->>Client: PRE_NONCE_REPLAY_DETECTED (fail-closed)
        else Nonce inédit
            LegalPreService->>DB: UPDATE used_nonces = used_nonces || nonce [INV-277-03]
            LegalPreService->>PRE: reEncrypt(reKey, payload)
            PRE-->>LegalPreService: ciphertext

            alt Échec re-chiffrement [INV-277-01]
                LegalPreService->>DB: ROLLBACK
                LegalPreService-->>Client: ERR-PERSISTENCE-CONTROL (fail-closed)
            else Succès
                LegalPreService->>DB: COMMIT
                Note over DB: Données at-rest chiffrées AES-256-GCM [INV-277-06]
                LegalPreService-->>Client: ciphertext (succès)
            end
        end
    end

10. Cas d’erreur¶

• ERR-NONCE-MISSING: nonce absent -> rejet.
• ERR-NONCE-FORMAT: nonce hors format contractuel -> rejet.
• PRE_NONCE_REPLAY_DETECTED: nonce déjà utilisé pour ce LegalReKey -> rejet.
• PRE_CERTIFICATE_BINDING_FAILED: certificat owner ou recipient absent/invalide/incompatible mandat -> rejet.
• ERR-PERSISTENCE-CONTROL: impossible de persister les données de contrôle (nonces/binding) -> rejet.
• ERR-PROLOG-FACTS-OUTDATED: faits non régénérés ou incohérents -> audit invalide.
• ERR-AUDIT-NONCOMPLIANT: résultat audit < 24/24 -> livraison refusée.

11. Critères d’acceptation (testables)¶

12. Scénarios de test (Given / When / Then)¶

• ST-277-01 (PKI nominal)
  Given un mandat valide et deux certificats valides
  When generateReKey est exécuté
  Then le LegalReKey est créé avec owner_certificate_id + recipient_certificate_id persistés.

• ST-277-02 (PKI owner absent/invalide)
  Given un mandat valide et certificat owner absent ou invalide
  When generateReKey est exécuté
  Then l’opération est rejetée avec PRE_CERTIFICATE_BINDING_FAILED.

• ST-277-03 (PKI recipient absent/invalide)
  Given un mandat valide et certificat recipient absent ou invalide
  When generateReKey est exécuté
  Then l’opération est rejetée avec PRE_CERTIFICATE_BINDING_FAILED.

• ST-277-04 (Nonce premier usage)
  Given un LegalReKey valide et un nonce UUID v4 lowercase ASCII inédit
  When reEncrypt est exécuté
  Then l’opération réussit et le nonce est marqué utilisé dans used_nonces.

• ST-277-05 (Nonce rejeu)
  Given un LegalReKey valide et un nonce déjà utilisé
  When reEncrypt est exécuté
  Then l’opération est rejetée (PRE_NONCE_REPLAY_DETECTED).

• ST-277-06 (Atomicité et concurrence)
  Given plusieurs requêtes concurrentes avec le même nonce et le même LegalReKey
  When reEncrypt est exécuté en parallèle
  Then au plus une requête réussit, les autres sont rejetées, et aucun état intermédiaire incohérent n’est persisté.

• ST-277-07 (Conformité Prolog)
  Given les faits Prolog régénérés après modifications
  When l’audit complet est lancé
  Then les checks 23 et 24 sont OK et le total bloquant est 24/24.

• ST-277-08 (Pas de nouvel état métier)
  Given le référentiel pré-PD-277 des StatusEnum des entités Legal*
  When la suite complète est exécutée post-PD-277
  Then aucun nouvel état/transition n’apparaît dans les enums métiers.

13. Hypothèses explicites¶

14. Contraintes techniques¶

Contraintes techniques (obligatoire)¶

• Projet cible: ProbatioVault-backend.
• Stack contractuelle: NestJS + TypeORM + PostgreSQL.
• Module impacté: legal-pre uniquement.
• Interdiction de changement de stack (pas de Spring Boot, pas de Swift/SwiftUI).
• Comparaisons sécuritaires conformes aux learnings (crypto.timingSafeEqual() lorsque applicable).

Bornes numériques obligatoires¶

SLA temporels¶

• Aucune transition temporelle métier nouvelle introduite par PD-277.
• TTL used_nonces aligné sur durée de vie du LegalReKey.

Transitions inverses (machine à états)¶

• Aucune transition retour applicable introduite par PD-277.
• Aucun nouvel état métier explicite.

Contraintes inter-modules¶

• Interaction identifiée avec composants PKI/mandat (validation inter-service).
• Aucune contrainte cross-route hors module explicitement ajoutée par PD-277.

15. Références¶

• Epic : PD-189 (CRYPTO)
• JIRA : PD-277
• Repos concernés : ProbatioVault-backend (principal), ProbatioVault-doc (template documentaire)
• Documents associés :
• Expression de besoin PD-277 (fournie)
• Learnings: PD-63, PD-41, PD-238
• Commande d’audit Prolog: swipl -l _generated-facts.pl -l pv_pre_compliance.pl -g "run_audit." -t "halt."