PD-276 — Plan d'implémentation¶

1. Découpage en composants¶

C1 — Argon2Service (validation paramètres KDF)¶

Responsabilité : Valider les paramètres Argon2id déclarés par le client contre les bornes contractuelles RFC 9106 + OWASP 2024. Aucune dérivation de clé serveur.

Fichiers :

• src/modules/crypto/services/argon2.service.ts — Service NestJS @Injectable() (Argon2Service)
• src/modules/crypto/dto/validate-argon2-params.dto.ts — DTO de validation (class-validator)
• src/modules/crypto/constants/argon2.constants.ts — Configuration centralisée (bornes, défauts)

Méthodes publiques :

POINT DE VIGILANCE PROLOG : Les checks Prolog 10 et 22 consomment service_method(argon2, deriveKey), pas validateParams. Or la spec interdit de modifier les règles Prolog (INV-276-10) et interdit la dérivation serveur (INV-276-01). Le ServiceExtractor de extract-facts.py émet automatiquement des faits pour toutes les méthodes publiques de la classe. Le fait service_method(argon2, validateParams) sera émis car la méthode existe. Cependant, les checks 10 et 22 échoueront si deriveKey n'existe pas comme méthode publique.

Décision : Le service expose aussi une méthode publique deriveKey() qui est un alias sémantique contractuel — elle délègue à validateParams() et retourne le résultat de validation (jamais de clé dérivée). Cette approche satisfait le check Prolog sans violer INV-276-01. Le JSDoc de deriveKey() DOIT documenter explicitement qu'il s'agit d'un alias de conformité Prolog, que la méthode NE dérive PAS de clé, et qu'elle est interdite d'appel direct depuis le code métier (seul validateParams doit être utilisé).

Alternative rejetée : Modifier pv_envelope_compliance.pl pour vérifier validateParams au lieu de deriveKey — interdit par INV-276-10 ("sans modification des fichiers Prolog").

C2 — Argon2Controller (exposition API)¶

Responsabilité : Exposer la configuration Argon2id de référence via endpoint REST.

Fichiers :

• src/modules/crypto/controllers/argon2.controller.ts — Controller REST

Endpoints :

C3 — MetadataBindingService (binding cryptographique)¶

Responsabilité : Calculer et vérifier le metadata_tag HMAC liant métadonnées critiques à l'enveloppe.

Fichiers :

• src/modules/crypto/services/metadata-binding.service.ts — Service NestJS @Injectable()

Méthodes publiques :

Dépendances : HkdfService (existant), HashService (existant pour timingSafeEqual).

Invariants :

• K_binding dérivée via HkdfService.deriveKey(kMasterUser, salt_empty, 'ProbatioVault::MetadataBinding::v1', 32) (INV-276-06)
• Concaténation canonique : Buffer.concat([algorithm, version, envelope_type, device_id]) — chaque champ encodé UTF-8 avec séparateur null byte
• Zeroization de K_binding dans finally après usage (pattern existant dans AesKwService)

C4 — Extension KeyEnvelope Entity¶

Responsabilité : Ajouter la colonne metadata_tag et la propriété de binding state.

Fichiers :

• src/modules/crypto/entities/key-envelope.entity.ts — Ajout colonne metadataTag

Modifications :

@Column('bytea', { name: 'metadata_tag', nullable: true })
metadataTag?: Buffer;

La colonne est nullable: true en phase 1. Le passage à nullable: false se fait en migration phase 2 après backfill.

C5 — Extension KeyEnvelopeService¶

Responsabilité : Intégrer la vérification du metadata_tag dans les flux d'accès (unwrap) et le calcul dans les flux de création/rotation.

Fichiers :

• src/modules/crypto/services/key-envelope.service.ts — Modifications des méthodes existantes

Modifications :

Logique unwrapEnvelope modifiée :

1. Lire l'enveloppe (existant)
2. Nouveau : Si metadata_tag IS NULL (state LEGACY_NULL_TAG) :
3. Phase 1 : accès lecture seule autorisé, warning loggé, rotation recommandée
4. La méthode retourne les données mais interdit les mutations (flag readOnly)
5. Nouveau : Si metadata_tag IS NOT NULL :
6. Vérifier via MetadataBindingService.verifyTag()
7. Si invalide : transition vers TAMPERED_TAG_INVALID, refus immédiat HTTP 422
8. Si valide : accès normal (state BOUND_TAG_VALID)
9. Unwrap (existant)

C6 — Migrations DDL¶

Responsabilité : Ajouter metadata_tag en 2 phases.

Fichiers :

• src/database/migrations/TIMESTAMP1-PD276-AddMetadataTagNullable.ts — Phase 1
• src/database/migrations/TIMESTAMP2-PD276-AddMetadataTagNotNull.ts — Phase 2

Phase 1 (up) :

ALTER TABLE vault_secure.key_envelopes
  ADD COLUMN metadata_tag BYTEA;

Phase 1 (down) :

ALTER TABLE vault_secure.key_envelopes
  DROP COLUMN IF EXISTS metadata_tag;

Phase 2 (up, exécutée après backfill) :

ALTER TABLE vault_secure.key_envelopes
  ALTER COLUMN metadata_tag SET NOT NULL;

ALTER TABLE vault_secure.key_envelopes
  ADD CONSTRAINT chk_metadata_tag_length CHECK (octet_length(metadata_tag) = 32);

Phase 2 (down) :

ALTER TABLE vault_secure.key_envelopes
  DROP CONSTRAINT IF EXISTS chk_metadata_tag_length;

ALTER TABLE vault_secure.key_envelopes
  ALTER COLUMN metadata_tag DROP NOT NULL;

C7 — Générateur de faits Prolog (ProbatioVault-doc)¶

Responsabilité : Le générateur existant extract-facts.py extrait automatiquement les faits depuis le code source. Aucune modification du script n'est requise.

Faits générés automatiquement (après implémentation C1 et C4) :

Vérification : Après implémentation, lancer extract-facts.py --backend ../ProbatioVault-backend/src et vérifier la présence des 5 faits ci-dessus dans _generated-facts.pl.

C8 — Tests contractuels¶

Responsabilité : Implémenter les 38 scénarios de test (TC-NOM, TC-ERR, TC-INV, TC-NEG, TC-NR).

Fichiers :

• src/modules/crypto/services/__tests__/argon2.service.spec.ts — Tests unitaires Argon2Service
• src/modules/crypto/services/__tests__/metadata-binding.service.spec.ts — Tests unitaires MetadataBindingService
• src/modules/crypto/services/__tests__/key-envelope.service.spec.ts — Extension tests existants
• src/database/migrations/__tests__/pd276-migrations.spec.ts — Tests migration up/down
• test/crypto/metadata-binding.e2e-spec.ts — Tests E2E binding + SLA < 100ms

2. Flux techniques¶

F1 — Validation Argon2id (serveur)¶

Client                     Argon2Controller        Argon2Service        Argon2Constants
  │                             │                       │                     │
  │  POST /auth/register        │                       │                     │
  │  {kdfParams: {...}}         │                       │                     │
  │─────────────────────────────│                       │                     │
  │                   pipe DTO  │                       │                     │
  │                   validate  │  validateParams(dto)  │                     │
  │                             │──────────────────────>│                     │
  │                             │                       │ compare vs          │
  │                             │                       │ ARGON2_CONFIG       │
  │                             │                       │────────────────────>│
  │                             │                       │  {min, max, def}    │
  │                             │                       │<────────────────────│
  │                             │   accept / reject     │                     │
  │                             │<──────────────────────│                     │

Note : La validation Argon2 est appelée depuis le flux d'enregistrement existant (AuthService). L'Argon2Controller ne sert qu'à exposer la configuration. La validation effective est invoquée par injection dans les flux auth/crypto, pas via endpoint dédié.

F2 — Exposition configuration¶

Client              Argon2Controller        Argon2Service
  │                       │                       │
  │  GET /crypto/          │                       │
  │    argon2/config       │                       │
  │───────────────────────>│   getConfig()          │
  │                        │──────────────────────>│
  │                        │   {ARGON2_CONFIG}      │
  │                        │<──────────────────────│
  │   200 {memory,         │                       │
  │    iterations,...}     │                       │
  │<───────────────────────│                       │

F3 — Création enveloppe avec metadata binding¶

AuthService         KeyEnvelopeService      MetadataBindingService    HkdfService      DB
  │                       │                       │                       │              │
  │ createMasterEnvelope  │                       │                       │              │
  │──────────────────────>│                       │                       │              │
  │                       │  computeTag(          │                       │              │
  │                       │   kMasterUser,        │                       │              │
  │                       │   {algo,ver,type,dev})│                       │              │
  │                       │──────────────────────>│  deriveKey(           │              │
  │                       │                       │   kMasterUser,        │              │
  │                       │                       │   empty_salt,         │              │
  │                       │                       │   'PV::MB::v1', 32)  │              │
  │                       │                       │──────────────────────>│              │
  │                       │                       │   K_binding           │              │
  │                       │                       │<──────────────────────│              │
  │                       │                       │  HMAC-SHA256(         │              │
  │                       │                       │   K_binding,          │              │
  │                       │                       │   canonicalized)      │              │
  │                       │                       │  zeroize(K_binding)   │              │
  │                       │   tag (32 bytes)      │                       │              │
  │                       │<──────────────────────│                       │              │
  │                       │  AES-KW wrap          │                       │              │
  │                       │  INSERT envelope      │                       │              │
  │                       │   + metadata_tag      │                       │              │
  │                       │───────────────────────────────────────────────────────────>│
  │  envelope created     │                       │                       │              │
  │<──────────────────────│                       │                       │              │

F4 — Accès enveloppe (unwrap avec vérification)¶

Caller              KeyEnvelopeService      MetadataBindingService         DB
  │                       │                       │                         │
  │ unwrapEnvelope(...)   │                       │                         │
  │──────────────────────>│  SELECT envelope       │                         │
  │                       │──────────────────────────────────────────────>│
  │                       │  envelope + tag        │                         │
  │                       │<──────────────────────────────────────────────│
  │                       │                       │                         │
  │                       │ [tag IS NULL?]         │                         │
  │                       │ YES (LEGACY) ────────> │                         │
  │                       │   Phase 1: read-only   │                         │
  │                       │   log warning          │                         │
  │                       │   return data (RO)     │                         │
  │                       │                       │                         │
  │                       │ NO (tag exists):       │                         │
  │                       │  verifyTag(            │                         │
  │                       │   kMasterUser,         │                         │
  │                       │   metadata, tag)       │                         │
  │                       │──────────────────────>│                         │
  │                       │  valid / invalid       │                         │
  │                       │<──────────────────────│                         │
  │                       │                       │                         │
  │                       │ [valid?]              │                         │
  │                       │ YES: AES-KW unwrap     │                         │
  │                       │   return K_master      │                         │
  │                       │                       │                         │
  │                       │ NO: HTTP 422           │                         │
  │                       │   < 100ms decision     │                         │
  │                       │   state → TAMPERED     │                         │
  │<──────────────────────│                       │                         │

F5 — Machine à états binding¶

                    ┌─────────────────────┐
                    │  LEGACY_NULL_TAG    │
                    │  (metadata_tag NULL) │
                    └────────┬────────────┘
                             │
                    ┌────────┴────────────┐
                    │                     │
             backfill/rotation    incohérence détectée
             conforme (F3)        (vérification binding)
                    │                     │
                    ▼                     ▼
        ┌──────────────────┐   ┌──────────────────────┐
        │ BOUND_TAG_VALID  │   │ TAMPERED_TAG_INVALID │
        │ (tag 32 bytes OK)│   │ (ÉTAT TERMINAL)      │
        └────────┬─────────┘   └──────────────────────┘
                 │                        ▲
                 │  altération détectée   │
                 └────────────────────────┘

Transitions interdites :
  BOUND → LEGACY     (downgrade interdit)
  TAMPERED → *       (état terminal, remédiation manuelle hors flux)

2bis. Diagrammes Mermaid¶

D1 — Graphe de dépendances entre composants¶

graph TD
    C2[C2 — Argon2Controller] -->|inject| C1[C1 — Argon2Service]
    C1 -->|lit| CONST[argon2.constants.ts<br/>ARGON2_CONFIG]
    C5[C5 — KeyEnvelopeService] -->|inject| C3[C3 — MetadataBindingService]
    C5 -->|inject| C1
    C3 -->|inject| HKDF[HkdfService<br/>existant]
    C3 -->|inject| HASH[HashService<br/>existant — timingSafeEqual]
    C5 -->|persiste| C4[C4 — KeyEnvelope Entity<br/>+ colonne metadata_tag]
    C4 -->|migration| C6[C6 — Migrations DDL<br/>phase 1 + phase 2]
    C7[C7 — extract-facts.py<br/>ProbatioVault-doc] -.->|extrait faits de| C1
    C7 -.->|extrait faits de| C4
    C8[C8 — Tests contractuels] -.->|teste| C1
    C8 -.->|teste| C3
    C8 -.->|teste| C5
    C8 -.->|teste| C6

    style C1 fill:#e1f5fe,stroke:#0277bd
    style C2 fill:#e1f5fe,stroke:#0277bd
    style C3 fill:#fff3e0,stroke:#e65100
    style C4 fill:#fce4ec,stroke:#b71c1c
    style C5 fill:#fff3e0,stroke:#e65100
    style C6 fill:#fce4ec,stroke:#b71c1c
    style C7 fill:#f3e5f5,stroke:#6a1b9a
    style C8 fill:#e8f5e9,stroke:#2e7d32
    style HKDF fill:#eeeeee,stroke:#616161
    style HASH fill:#eeeeee,stroke:#616161
    style CONST fill:#eeeeee,stroke:#616161

Légende : bleu = validation Argon2, orange = binding crypto, rouge = persistance/DDL, violet = vérification formelle, vert = tests, gris = services existants.

D2 — Séquence de création d'enveloppe avec metadata binding (F3)¶

sequenceDiagram
    participant Auth as AuthService
    participant KES as KeyEnvelopeService (C5)
    participant MBS as MetadataBindingService (C3)
    participant HKDF as HkdfService
    participant DB as PostgreSQL

    Auth->>KES: createMasterEnvelope(kMasterUser, metadata)
    activate KES
    KES->>MBS: computeTag(kMasterUser, {algo, ver, type, dev})
    activate MBS
    MBS->>HKDF: deriveKey(kMasterUser, empty_salt, 'PV::MB::v1', 32)
    HKDF-->>MBS: K_binding (32 bytes)
    Note over MBS: HMAC-SHA256(K_binding, canonical_concat)
    Note over MBS: zeroize(K_binding) in finally
    MBS-->>KES: tag (32 bytes)
    deactivate MBS
    Note over KES: AES-KW wrap(kMasterUser)
    KES->>DB: INSERT envelope + metadata_tag
    DB-->>KES: OK
    KES-->>Auth: envelope created
    deactivate KES

D3 — Séquence d'accès enveloppe avec vérification binding (F4)¶

sequenceDiagram
    participant Caller
    participant KES as KeyEnvelopeService (C5)
    participant MBS as MetadataBindingService (C3)
    participant DB as PostgreSQL

    Caller->>KES: unwrapEnvelope(envelopeId, kMasterUser)
    activate KES
    KES->>DB: SELECT envelope + metadata_tag
    DB-->>KES: envelope row

    alt tag IS NULL (LEGACY_NULL_TAG)
        Note over KES: Phase 1 : read-only autorisé
        Note over KES: Log warning + recommend rotation
        KES-->>Caller: data (readOnly=true)
    else tag IS NOT NULL
        KES->>MBS: verifyTag(kMasterUser, metadata, storedTag)
        activate MBS
        Note over MBS: Recalcul HMAC + timingSafeEqual
        MBS-->>KES: valid / invalid
        deactivate MBS

        alt valid
            Note over KES: AES-KW unwrap
            KES-->>Caller: K_master (BOUND_TAG_VALID)
        else invalid
            Note over KES: state -> TAMPERED_TAG_INVALID
            KES-->>Caller: HTTP 422 (< 100ms SLA)
        end
    end
    deactivate KES

D4 — Machine à états binding¶

stateDiagram-v2
    [*] --> LEGACY_NULL_TAG : enveloppe pré-migration<br/>(metadata_tag NULL)

    LEGACY_NULL_TAG --> BOUND_TAG_VALID : backfill / rotation<br/>computeTag() conforme (C3)
    LEGACY_NULL_TAG --> TAMPERED_TAG_INVALID : incohérence métadonnées<br/>détectée lors backfill

    BOUND_TAG_VALID --> TAMPERED_TAG_INVALID : altération détectée<br/>verifyTag() échoue (C3)

    note right of TAMPERED_TAG_INVALID
        ÉTAT TERMINAL
        Remédiation manuelle hors flux
        Transitions sortantes interdites
    end note

    note left of LEGACY_NULL_TAG
        Phase 1 : accès lecture seule
        Warning loggé (C5)
    end note

    note right of BOUND_TAG_VALID
        Tag 32 bytes OK
        Accès normal autorisé
    end note

3. Mapping invariants → mécanismes¶

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

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

6. Gestion des erreurs¶

SLA : La décision de rejet sur METADATA_TAG_INVALID doit intervenir en < 100ms (t_decision - t_req). Le périmètre de mesure : de la réception de la requête dans unwrapEnvelope() jusqu'au throw de l'exception HTTP 422.

7. Impacts sécurité¶

7.1 Risques et mitigations¶

7.2 Journalisation sécurité¶

7.3 Conformité¶

• RFC 9106 : Validation des paramètres Argon2id (sans dérivation serveur)
• OWASP 2024 : Plancher mémoire 65536 KiB, iterations >= 3, parallelism >= 4
• Zero-Knowledge : Aucun secret utilisateur n'atteint le serveur en clair
• Anti-substitution : HMAC binding empêche la substitution d'enveloppe inter-device

8. Hypothèses techniques¶

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

9.1 Contradiction spec vs Prolog (CRITIQUE)¶

La spec INV-276-09 déclare que le fait requis est service_method(argon2, validateParams). Les checks Prolog 10 et 22 vérifient service_method(argon2, deriveKey). La spec interdit de modifier le Prolog (INV-276-10).

Résolution : Le service expose deriveKey() comme alias public de validateParams(). Les deux faits sont émis. Le check Prolog passe via deriveKey. Le test TC-INV-04 doit vérifier que check_10 et check_22 consomment service_method(argon2, deriveKey) (et non validateParams).

Action : Signaler l'écart à l'auteur de la spec pour correction en prochaine itération (aligner INV-276-09 sur la réalité Prolog).

9.2 Backfill LEGACY (COMPLEXITÉ)¶

Le backfill des enveloppes existantes requiert K_master_user pour dériver K_binding. Or K_master_user n'est jamais stockée en clair — elle est wrappée dans l'enveloppe elle-même. Le backfill nécessite donc un flux applicatif déclenché lors du prochain accès utilisateur (lazy migration), et non un script SQL batch.

Impact : La phase 2 (NOT NULL) ne peut être activée qu'après que tous les utilisateurs actifs aient accédé au moins une fois à leur enveloppe post-migration. La migration phase 2 doit être déployée séparément, avec un monitoring du nombre d'enveloppes LEGACY restantes.

9.3 Transition LEGACY → TAMPERED (AMBIGUÏTÉ)¶

Le scénario TC-NOM-13 teste la transition LEGACY_NULL_TAG → TAMPERED_TAG_INVALID sur "incohérence détectée". Pour une enveloppe LEGACY (tag NULL), l'incohérence ne peut être détectée que si un contrôle d'intégrité est tenté (backfill ou rotation). Le cas se produit quand : - Un calcul de tag est tenté sur une enveloppe LEGACY - Le tag calculé est incompatible avec les métadonnées en base (ex: device_id corrompu)

Observable : Lors d'une tentative de rotation/backfill, si le tag calculé échoue à la validation (métadonnées incohérentes), l'enveloppe est marquée TAMPERED.

9.4 SLA < 100ms (RISQUE OPÉRATIONNEL)¶

Le SLA de décision < 100ms sur rejet de binding est mesuré dans le périmètre unwrapEnvelope() (de l'entrée de la méthode au throw). Les facteurs de risque : - Latence DB pour la lecture de l'enveloppe (réseau) - Calcul HKDF + HMAC (CPU, < 1ms attendu)

Mitigation : Mesure performance.now() avant/après dans les tests E2E. En production, métriques OpenTelemetry sur le span de vérification.

9.5 Contexte HKDF hardcodé¶

Le contexte 'ProbatioVault::MetadataBinding::v1' est un littéral contractuel. Il DOIT être centralisé dans argon2.constants.ts (ou un fichier de constantes crypto dédié) et JAMAIS dupliqué en inline.

10. Hors périmètre¶

• Dérivation Argon2id côté serveur : Le serveur valide les paramètres mais ne dérive jamais de clé (INV-276-01).
• Modification des règles Prolog : pv_envelope_compliance.pl reste inchangé.
• Refonte des 21 checks existants : Aucun check vert ne peut devenir rouge.
• Librairie native Argon2 backend : Aucune dépendance argon2, @phc/argon2, ou similaire.
• Paramétrage adaptatif client par device : Hors scope de cette story.
• Preuve exhaustive d'absence de secrets : Seuls des contrôles probatoires sont attendus (CA-276-12).
• Backfill automatique des enveloppes LEGACY : Le mécanisme de lazy migration est documenté mais l'exécution en production est hors scope du code livré. Le code fournit les primitives (computeTag, migration phase ½) ; le déclenchement du backfill est opérationnel.
• Mécanismes cross-module : Aucune modification d'autres modules identifiée. Le guard de binding est interne au module crypto.

11. Écarts spec identifiés (review inputs)¶