PD-287 — Plan d'implémentation¶

Stack cible : ProbatioVault-backend (NestJS + TypeORM + PostgreSQL). Aucune autre pile n'est visée.

Hypothèse contractuelle retenue : le backend expose déjà vault_secure.proofs (service Proofs), un module Crypto (HSM + KMS envelope), un service Mail transactionnel, un journal d'audit plateforme, un rate-limiter distribué (Redis) et un orchestrateur de workers. Le présent plan s'insère comme module SharingModule + workers dédiés, sans fork de modules existants.

1. Découpage en composants¶

2. Flux techniques¶

2.1 F-287-01 — Création du lien (propriétaire)¶

1. POST /shares avec proof_id, recipient_email, ttl_seconds?, header Idempotency-Key.
2. SharingController valide le payload via DTO + class-validator (regex §5.1).
3. Acquisition lock Redis share:create:{proof_id}:{recipient_email} TTL 600s → 409 SHARE_BUSY sinon.
4. Vérification idempotence : share_idempotency_keys(key=sha256(key+canonicalJson(payload))) → 409 IDEMPOTENCY_CONFLICT si payload différent, 409 IDEMPOTENCY_WINDOW_EXPIRED si hors fenêtre 24h.
5. Vérification ownership preuve via ProofsService.assertOwner(proof_id, userId).
6. Vérification quotas (C7 expose QuotaCheckService interrogé via repository share_quota_counters) : create_links_per_proof_per_24h, create_links_per_owner_per_24h, active_links_per_owner_max.
7. PreCryptoService.generateEphemeralIdentity() → recipient_ephemeral_pubkey_pem, cert signé par CA plateforme (DER b64). Aucun stockage du secret privé côté backend (la clé privée n'est jamais générée côté serveur ; seuls la pubkey et la capsule PRE transitent).
8. PreCryptoService.reKeyGen(owner_key_ref, recipient_ephemeral_pubkey) → pre_rekey_envelope_b64 (chiffré KMS).
9. Génération token : 32 octets CSPRNG crypto.randomBytes(32) → base64url 43 chars. Persistence de sha256(token) comme PK indexée ; le token clair n'est jamais stocké.
10. Transaction SQL unique :
    • INSERT share_links (id, proof_id, owner_user_id, recipient_email_lower, token_sha256, state='PENDING_ACTIVATION', created_at, expires_at=created_at+ttl, pre_rekey_envelope_b64, recipient_ephemeral_cert_der_b64, encrypted_dek_envelope_b64)
    • AuditJournalService.append(LINK_CREATED, share_link_id, prev_hash) bloquant dans la même transaction (pattern outbox pas utilisé ici — l'audit est synchrone §5.7).
    • Commit.
11. Libération lock. Réponse 201 { share_url_token, share_link_id, state, expires_at_utc } au propriétaire uniquement.

2.2 F-287-02 — Activation destinataire OTP¶

1. GET /sharing/:token : résolution token_sha256, check état PENDING_ACTIVATION + non expiré. Si KO → 404 générique (§INV-287-12).
2. OtpService.emitOtp(share_link_id, recipient_email) :
3. Contrôle otp_resend_limit_per_hour (Redis counter fenêtre glissante 1h).
4. Génère code 6 digits via crypto.randomInt(0, 1_000_000) (pas Math.random() — cf. learning crypto.randomUUID() 2026-02-21, même justification S2245).
5. Stocke sha256(otp_code) + emitted_at_utc + valid_until_utc = emitted_at_utc + OTP_CODE_TTL_SECONDS (nouvelle constante OTP_CODE_TTL_SECONDS=300s, cf. Point de vigilance #10).
6. Envoi email via MailService.sendOtp().
7. Retour 200 (pas de différenciation succès/rate-limit vers destinataire autre que 429 rate-limit).
8. POST /sharing/:token/activate { otp_code } :
9. Lock Redis share:otp:{share_link_id} TTL 30s (empêche concurrence session).
10. Chargement share_otp_state (compteur session otp_attempt_count, cumulé otp_failed_attempts_total).
11. Comparaison timing-safe crypto.timingSafeEqual(sha256(input), stored_sha256) + check non péremption OTP.
12. Si OK : transition PENDING_ACTIVATION → ACTIVE, création session recipient_session_id, reset otp_attempt_count=0, append audit LINK_ACTIVATED.
13. Si KO et otp_attempt_count < 4 : 404 générique, incrément session + cumulé.
14. Si KO et otp_attempt_count == 4 (5e échec) : transition → OTP_BLOCKED, otp_blocked_until_utc = now + 900s, incrément blocages → hook NotificationDispatcher si 3e blocage, append audit. Réponse 429 (suit §5.4 F-287-02, cf. Point de vigilance #1).
15. Si otp_failed_attempts_total >= 50 après incrément : transition → REVOKED, notification propriétaire, append audit LINK_REVOKED. Réponse 429.
16. Déverrouillage automatique OTP_BLOCKED → ACTIVE exécuté par ReconciliationWorker (tick 60s) OU à la prochaine tentative OTP valide si cooldown expiré.

2.3 F-287-03 — Consultation de la preuve¶

1. GET /sharing/:token/proof avec header X-Recipient-Session: <recipient_session_id>.
2. ShareProofGuard (C12) : valide token, charge share_link, vérifie state=ACTIVE, expiration, session non expirée (last_activity + 1800s).
3. Si session invalide → 404 générique + indication UX de réauth via /reauth/request-otp (enveloppe standard { reauth_required: true } sans différencier existence lien).
4. Mise à jour session last_activity = now.
5. PreCryptoService.reEncrypt(encrypted_dek_envelope, pre_rekey_envelope) → recipient_capsule_encrypted_b64.
6. ProofsService.getEncryptedDocument(proof_id) retourne le document chiffré (interprétation plan : le document chiffré est streamé inline en base64 ou via flux binaire dans la réponse — cf. Point de vigilance #2 et ADR-287-01).
7. AuditJournalService.append(LINK_VIEWED, ...) avant émission de la réponse (synchrone bloquant). Si append échoue → 503 fail-closed, réponse vidée.
8. Réponse 200 { encrypted_document_b64, recipient_capsule_encrypted_b64, proof_hash_sha256_hex, merkle_proof_canonical_json, tsa_token_der_b64, blockchain_anchor_txid_hex }.

2.4 F-287-04 — Export composite (optionnel)¶

1. Feature flag export_zip_enabled=false par défaut. Si false → 404 générique sur POST /sharing/:token/export (pas de différenciation de capability).
2. Si true et session valide : ExportComposerService construit :
3. /document.bin (copie chiffrée, capsule PRE en métadonnée)
4. /proof.json (hash+Merkle+TSA+anchor)
5. /audit-subset.jsonl (événements LINK_* strictement liés à ce lien)
6. /manifest.json (JCS canonical, clés minimales §D-287-26)
7. /manifest.sig (signature ECDSA P-384 par clé plateforme HSM)
8. /platform-cert.pem (cert plateforme + chaîne racine)
9. Check size <= export_zip_max_size_mb → 413 sinon (avant streaming).
10. AuditJournalService.append(LINK_EXPORTED, export_zip_sha256_hex) synchrone.
11. Streaming ZIP vers destinataire.

2.5 F-287-05 — Révocation¶

1. POST /shares/:id/revoke (owner) → lock share:lifecycle:{id}.
2. Transaction : UPDATE state→REVOKED, revoked_at_utc=now, invalidation share_sessions actives (table flag), append audit LINK_REVOKED bloquant.
3. Publication event Redis share.revoked → RecipientSessionService purge cache session local (coupure au round-trip suivant, cf. CA-287-08).
4. RetentionWorker rescheduled pour J+90.

2.6 F-287-06 — Expiration TTL¶

• Worker cron 30s scanne share_links WHERE state IN ('PENDING_ACTIVATION','ACTIVE','OTP_BLOCKED') AND expires_at < now().
• Transition batch → EXPIRED, append LINK_EXPIRED + invalidation sessions + purge artefacts temporaires.
• Réponses destinataire post-expiration : 404 générique.

2.7 F-287-07 — Vue propriétaire¶

• GET /shares?state=active|all paginé. GET /shares/:id/events renvoie événements liés au lien (depuis share_audit_events scopé share_link_id).
• Premier affichage UI propriétaire : flag user_preferences.noDrmWarningAcknowledged (scope compte utilisateur serveur — cf. Point de vigilance #16 et ADR-287-02).

2bis. Diagramme de dépendances agents¶

graph LR
    subgraph Wave1[Wave 1 - fondations]
        C13[agent-sharing-api/migrations<br/>C13 DDL]
        C9[agent-trust-store<br/>C9]
        C5[agent-audit-journal<br/>C5 append + hash-chain]
    end
    subgraph Wave2[Wave 2 - services crypto et session]
        C4[agent-crypto-pre<br/>C4]
        C2[agent-otp<br/>C2]
        C3[agent-recipient-session<br/>C3]
        C11[agent-notifications<br/>C11]
    end
    subgraph Wave3[Wave 3 - API + guard + workers]
        C1[agent-sharing-api<br/>C1 + C12 guard]
        C6[agent-audit-journal<br/>C6 Merkle worker]
        C7[agent-reconciliation-worker<br/>C7]
        C8[agent-retention-worker<br/>C8]
        C10[agent-export<br/>C10]
    end
    subgraph Wave4[Wave 4 - tests]
        C14[agent-tests<br/>Unit+Int+E2E+Perf+Sec]
    end

    C13 --> C4
    C13 --> C2
    C13 --> C3
    C13 --> C5
    C9 --> C4
    C5 --> C1
    C5 --> C6
    C5 --> C7
    C5 --> C8
    C5 --> C10
    C4 --> C1
    C4 --> C10
    C2 --> C1
    C3 --> C1
    C11 --> C2
    C11 --> C3
    C1 --> C14
    C6 --> C14
    C7 --> C14
    C8 --> C14
    C10 --> C14

Lecture : 4 waves. Wave 1 livre les fondations (DDL + trust-store + audit service). Wave 2 livre les services middleware (crypto PRE, OTP, sessions, notifications). Wave 3 livre l'API, le guard cross-module et les workers. Wave 4 produit la suite de tests. Les agents d'une même wave sont parallélisables.

2ter. Mécanismes cross-module (obligatoire)¶

3. Mapping invariants → mécanismes¶

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

5. Mapping tests → mécanismes + observables¶

5bis. Périmètre de test¶

Couverture minimale attendue : 80 % lignes + 80 % branches sur le périmètre in-scope (C1–C12). Seuils mesurés via Jest coverage + --coverageThreshold.

6. Gestion des erreurs¶

Palette HTTP et mapping :

Anti-catch-absorb (learning 2026-03-08) : tout catch qui appelle auditLog DOIT re-throw OU utiliser finally. Règle ESLint custom audit-must-throw déployée.

7. Impacts sécurité¶

Conformité RGPD : - Consentement RGPD affiché avant activation (CA-287-27, côté front stubbé). - Droit à l'oubli : RetentionWorker J+90 ; request DELETE /owner/shares/:id/recipient-data possible en avance sur purge automatique (hors spec MVP — tracé PD-287-EXT-2). - Audit conservation légale : justifiée par valeur probatoire (art. 6.1.c RGPD obligation légale / 6.1.f intérêt légitime).

8. Hypothèses techniques¶

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

1. Anti-enumeration vs 429 (écart Gate 3 #1 — Bloquant) : spec impose 429 sur OTP_BLOCKED/REVOKED, INV-287-12 impose 404 homogène. Plan suit spec (429) + jitter latence. Risque résiduel de fingerprinting par latence ; documenté et accepté ; à reconfronter Gate 8 via métriques.
2. Format payload consultation (écart #2 — Bloquant) : ADR-287-01 retient le document chiffré inline (base64) dans la réponse JSON vs URL présignée, car INV-287-01 interdit l'exposition d'un flux clair et une URL présignée impliquerait un service Proofs servant du chiffré — acceptable mais plus de surface. Taille borne : max_inline_document_bytes = 50 MB, au-delà → 413 ou streaming binaire application/octet-stream multipart (tracé PD-287-LARGE).
3. Endpoints reauth (écart #3 — Bloquant) : plan les formalise (POST /sharing/:token/reauth/request-otp, POST /sharing/:token/reauth/confirm) avec le même rate-limit et la même anti-enum que l'activation initiale. Audit event LINK_REAUTH_* ajouté (hors enum D-287-23 — extension spec mineure à tracer dans YAML index).
4. DoS via seuil OTP cumulé (écart #4 — Bloquant) : plan suit spec (REVOKED terminal). Mitigation : rate-limit IP en amont + possibilité pour owner de recréer un lien. Piste d'évolution tracée PD-287-EXT-1 (seuil intermédiaire non-terminal).
5. SLA P95 non déterministe en test unitaire (écart #5 — Bloquant) : exige suite perf dédiée (k6 N≥200). TC-NOM-09 split en TC-NOM-09a (fonctionnel single-request) et TC-NOM-09b (perf). Budget CI : job nightly perf-staging.
6. FSM no-op (écart #6 — Majeur) : ShareStateMachine.transition(from, to) où from==to → throw ForbiddenTransitionError côté API, mapping 409 owner / 404 destinataire. Plan explicite.
7. INV-287-08 configurabilité (écart #7 — Majeur) : plan fixe valeur non configurable MVP (constante REVOCATION_P95_SLA_MS=2000), conforme §5.3.
8. Reset compteur OTP session (écart #8 — Majeur) : plan documente reset sur transition OTP_BLOCKED→ACTIVE + sur ACTIVE frais (post-activation valide). Règle explicitée dans OtpService.resetSessionCounter().
9. Formats owner_key_ref / encrypted_doc_ref (écart #9 — Majeur) : plan définit owner_key_ref = HSM KeyHandle (opaque string ≤ 128 chars) et encrypted_document = base64 inline (cf. point 2). À proposer comme extension au §5.1 spec.
10. OTP TTL (écart #10 — Majeur) : OTP_CODE_TTL_SECONDS=300s (5 min) par défaut. Cohérent avec pratique OTP mail (Stripe 15min, GitHub 10min — 5min plus strict). Ajuster Gate 5 si PO challenge.
11. Grep mémoire process non déterministe (écart #11 — Majeur) : TC-INV-11 formalisé en protocole reproductible : (1) lancer test sous Node --expose-gc, (2) déclencher cycle complet, (3) global.gc() ×3, (4) process.memoryUsage().heapSnapshot, (5) grep heap dump (node --heapsnapshot-signal=SIGUSR2) pour motifs document clair. Tolérance : heap dump post-3×GC sans motif. Script scripts/security/memory-scan.sh.
12. max_consultations_per_link (écart #12 — Majeur) : paramètre §5.2 sans contrat → plan traite comme feature optionnelle désactivée par défaut (max_consultations_per_link=0 → illimité). Si activé par config : incrément compteur sur LINK_VIEWED, transition → EXPIRED quand atteint + LINK_EXPIRED(reason: consultation_limit). Pas de test obligatoire MVP (feature dormante).
13. 429 sur états FSM (écart #13 — Majeur) : plan applique 429 + Retry-After non informatif (Retry-After: 0 pour REVOKED), conformité spec. Risque de monitoring ambigu mitigé par label métrique retry_reason.
14. Ordre Merkle multi-batchs (écart #14 — Majeur) : plan impose worker Merkle mono-instance via pg_advisory_lock + audit_sequence_number strictement monotone (BIGSERIAL) + batchs ordonnés par séquence. Post-crash : reprise depuis le dernier batch ancré confirmé.
15. Chiffrement données destinataire (écart #15 — Majeur) : plan ajoute chiffrement pgp_sym_encrypt clé KMS sur recipient_email/client_ip/user_agent. Migration + index hashé pour recherche.
16. Scope mémorisation warning DRM (écart #16 — Majeur) : ADR-287-02 retient compte utilisateur serveur.
17. Idempotence canonique (écart #17 — Majeur) : JCS RFC 8785. Documenté dans l'API (Idempotency-Key doc page).
18. Borne D-287-31 vs seuil REVOKED (écart #18 — Mineur) : plan définit check count >= 50 avant incrément (sémantique : la 50e tentative échouée déclenche REVOKED, stockage max 49 ou 50 selon transaction). Garde-fou race via lock OTP.
19. H-287-07 manquante (écart #19 — Mineur) : coquille spec. Plan non impacté.
20. Export skip (écart #20 — Mineur) : tests export describe.skip conditionnel sur process.env.EXPORT_ZIP_ENABLED !== 'true'. Documenté CI.
21. D-287-09 formule vs regex (écart #21 — Mineur) : plan traite comme règle de cohérence, validée par trigger PG CHECK (expires_at = created_at + make_interval(secs => ttl_seconds)).
22. Ownership mutable (écart #22 — Mineur) : plan documente hypothèse ownership immuable durant la vie du lien. Si futur transfert : REVOKED automatique (trigger PG ON UPDATE proofs.owner_user_id). Hors périmètre MVP, tracé PD-287-EXT-3.
23. Diagramme d'état incomplet (écart #23 — Mineur) : plan ne modifie pas la spec, documente en annotation.
24. Périmètre INV-287-01 (écart #24 — Mineur) : plan énumère le périmètre d'audit : services C1, C2, C3, C4, C5, C6, C7, C8, C10, C12 + logs applicatifs + DB secondaires (replicas). Exclu : systèmes externes (HSM, KMS, Blockchain client).
25. Trust-store incomplet (écart #25 — Mineur) : définition formelle dans TrustStoreService.
26. Événements audit hors enum D-287-23 : plan étend l'enum contractuel audit_event_type avec 3 événements additionnels : LINK_OTP_BLOCKED, LINK_REAUTH_REQUESTED, LINK_REAUTH_CONFIRMED. Ces événements sont inclus dans la même chaîne hash et le même journal append-only (pas de table séparée). Cette extension est une correction spec proposée alignée sur les flux réauth documentés dans la spec §5.5. Les tests TC correspondants doivent couvrir ces événements.
27. Charge Redis : single-instance staging MVP. Multi-instance → tracé PD-287-HA.
28. HSM rate-limit : PreCryptoService peut saturer HSM en cas de pic. Circuit breaker (opossum) + file d'attente bornée.

10. Hors périmètre¶

• Front destinataire (web/mobile) : livré par story dédiée (stub PD-287-FRONT). Les tests contractuels TC-NOM-02 (info RGPD avant activation) et TC-NOM-11 (warning DRM propriétaire) sont vérifiés côté backend via les réponses API (champ rgpd_notice_url dans la réponse activation, champ no_drm_ack_required dans la réponse création). La vérification UI complète est déléguée à PD-287-FRONT.
• Pentest manuel tiers : PD-287-PENTEST.
• Multi-instance HA Redis/Postgres : PD-287-HA.
• Pages OAuth / SSO destinataire (invitation remplace compte) : hors scope par spec.
• Mobile offline consultation : exclu par spec §2.
• Partage inter-comptes ProbatioVault : exclu par spec.
• Décision judiciaire admissibilité : non technique.
• Révocation partielle (consultation vs export) : exclue par spec.
• Heartbeats signés (preuve d'absence d'accès) : hors MVP.
• Transfert ownership pendant vie du lien : PD-287-EXT-3.
• Seuil intermédiaire non-terminal anti-DoS OTP : PD-287-EXT-1.
• API DELETE /owner/shares/:id/recipient-data on-demand : PD-287-EXT-2.
• Scénarios perf sur-nominaux : PD-287-PERF-EXT.
• Performance multi-instance / failover : hors périmètre MVP.

Annexe A — ADR courts¶

ADR-287-01 — Livraison du document chiffré destinataire - Contexte : spec §5.4 F-287-03 dit "document chiffré" ; diagramme dit encrypted_doc_ref. - Décision : livraison inline base64 dans la réponse JSON (jusqu'à 50 MB), sinon stream binaire. - Conséquences : simplicité de l'atomicité zero-knowledge, pas de second service exposé. Charge réseau accrue vs URL présignée ; acceptable pour documents probatoires (<= 50 MB typique).

ADR-287-02 — Scope mémorisation warning "pas de DRM" - Contexte : écart Gate 3 #16. - Décision : persistance serveur au niveau compte utilisateur (user_preferences.no_drm_ack_at_utc). - Conséquences : cohérence multi-device, testable server-side, aligné privacy (pas de cookie).

ADR-287-03 — Worker Merkle mono-instance - Contexte : écart Gate 3 #14. - Décision : pg_advisory_lock garantit un seul worker actif simultané ; séquenceur audit_sequence_number strict. - Conséquences : SPOF worker (mitigé par failover rapide via advisory lock release sur crash TCP). Alternative multi-instance avec coordination (ZooKeeper/etcd) hors périmètre MVP.