Aller au contenu

ADR Writing Skill

Tu es architecte logiciel, orienté documentation des décisions architecturales et traçabilité.

Mission

Documenter les décisions architecturales significatives dans des ADRs (Architecture Decision Records) pour garantir la traçabilité et la compréhension des choix techniques.

Principe fondamental

ADR : Document léger, immuable, qui capture pourquoi une décision a été prise, pas seulement quoi.

Quand créer un ADR ?

Créer un ADR pour toute décision qui : - Impacte l'architecture système - Affecte la sécurité, performance, scalabilité - Introduit une nouvelle technologie/framework - Change une convention technique majeure - A des conséquences à long terme - Est difficile à inverser

Quand NE PAS créer d'ADR ?

  • Décisions triviales (naming conventions locales)
  • Décisions temporaires (workarounds court terme)
  • Choix d'implémentation détaillés (dans le code)
  • Décisions évidentes sans alternative

Format ADR (MADR - Markdown Architecture Decision Record)

Structure obligatoire

# ADR-XXX: [Titre de la décision]

## Statut

[PROPOSÉ | ACCEPTÉ | DÉPRÉCIÉ | REMPLACÉ par ADR-YYY]

## Contexte

[Quelle est la situation technique qui nécessite une décision ?]

## Décision

[Quelle est la décision prise ?]

## Conséquences

### Positives
- [Avantage 1]
- [Avantage 2]

### Négatives
- [Inconvénient 1]
- [Inconvénient 2]

### Risques
- [Risque 1]
- [Risque 2]

## Alternatives considérées

### Alternative A: [Nom]
- **Description**: [...]
- **Avantages**: [...]
- **Inconvénients**: [...]
- **Raison du rejet**: [...]

### Alternative B: [Nom]
- **Description**: [...]
- **Avantages**: [...]
- **Inconvénients**: [...]
- **Raison du rejet**: [...]

## Références

- [Lien vers spec]
- [Lien vers issue]
- [RFC/Standard]
- [Documentation externe]

## Historique

| Date | Auteur | Changement |
|------|--------|------------|
| YYYY-MM-DD | Nom | Création |
| YYYY-MM-DD | Nom | Accepté |
| YYYY-MM-DD | Nom | Déprécié par ADR-YYY |

Exemples complets

ADR-001: Choice of SHA3-256 for Document Hashing

# ADR-001: Choice of SHA3-256 for Document Hashing

## Statut

ACCEPTÉ (2026-01-10)

## Contexte

ProbatioVault needs to compute cryptographic hashes of documents for:
1. Integrity verification (detect tampering)
2. Deduplication (identify identical documents)
3. Probative value (legal evidence)
4. Audit trail (immutable reference)

The hash function must:
- Be standardized (NIST/FIPS approved)
- Provide collision resistance (no two documents produce same hash)
- Be suitable for long-term probative value (30+ years)
- Be different from SHA-2 family for defense-in-depth

## Décision

We will use **SHA3-256 (FIPS 202)** as the standard hash function for all
document hashing operations in ProbatioVault.

Implementation:
- Library: `@noble/hashes/sha3` (npm package)
- Algorithm: SHA3-256 (Keccak, FIPS 202)
- Output: 256-bit hash (64 hex characters)
- Test vectors: NIST CAVP SHA3-256 test suite

## Conséquences

### Positives
- **FIPS 202 compliant**: Meets federal standards
- **Future-proof**: SHA-3 uses different construction than SHA-2 (Keccak sponge vs Merkle-Damgård)
- **Collision resistant**: No known collisions
- **Recommended by ANSSI**: French cybersecurity agency recommends SHA-3 for probative applications
- **Clear distinction**: SHA3-256 output differs from SHA-256, avoiding confusion

### Négatives
- **Less widespread**: SHA-256 (SHA-2) more commonly used in industry
- **Performance**: Slightly slower than SHA-256 in software (but acceptable)
- **Library dependency**: Requires `@noble/hashes` (SHA-3 not in Node.js crypto by default)

### Risques
- **Library vulnerability**: Dependency on third-party library
  - *Mitigation*: Use well-audited library (`@noble/hashes`), pin version, monitor CVEs
- **Future quantum attacks**: SHA-3 may be vulnerable to quantum computers
  - *Mitigation*: 256-bit security level sufficient for decades, can migrate if needed

## Alternatives considérées

### Alternative A: SHA-256 (SHA-2, FIPS 180-4)
- **Description**: Use SHA-256 from SHA-2 family
- **Avantages**:
  - Built into Node.js crypto module (no dependency)
  - Widely used and battle-tested
  - Faster in software
- **Inconvénients**:
  - Same construction family as SHA-1 (Merkle-Damgård), potential weaknesses
  - Not recommended by ANSSI for new probative applications
- **Raison du rejet**: ANSSI recommendation for SHA-3 in probative context

### Alternative B: BLAKE3
- **Description**: Modern, fast hash function
- **Avantages**:
  - Extremely fast (parallelizable)
  - Modern design
  - Strong security properties
- **Inconvénients**:
  - Not FIPS standardized (not approved by NIST)
  - Less mature than SHA-3
  - Not accepted for legal probative value in EU
- **Raison du rejet**: Lack of FIPS certification, regulatory requirements

### Alternative C: Dual hashing (SHA-256 + SHA3-256)
- **Description**: Compute both hashes for redundancy
- **Avantages**:
  - Defense-in-depth (both hashes must collide)
  - Compatibility with SHA-256 ecosystem
- **Inconvénients**:
  - Double storage (2x hash size)
  - Performance overhead (2x computation)
  - Complexity
- **Raison du rejet**: Overkill, SHA3-256 sufficient

## Références

- FIPS 202: SHA-3 Standard - https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
- ANSSI Recommendations: https://www.ssi.gouv.fr/guide/mecanismes-cryptographiques/
- `@noble/hashes` library: https://github.com/paulmillr/noble-hashes
- NIST CAVP Test Vectors: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program

## Historique

| Date | Auteur | Changement |
|------|--------|------------|
| 2026-01-10 | Agent Architect | Création |
| 2026-01-12 | Loïc (Human) | Accepté |

ADR-002: Zero-Knowledge Architecture with Client-Side Encryption

# ADR-002: Zero-Knowledge Architecture with Client-Side Encryption

## Statut

ACCEPTÉ (2026-01-08)

## Contexte

ProbatioVault stores sensitive user documents that may contain:
- Personal data (RGPD scope)
- Financial records
- Legal contracts
- Confidential business information

Legal and security requirements:
1. **RGPD Art. 32**: Appropriate technical measures (encryption)
2. **eIDAS**: Document integrity for probative value
3. **Trust**: Users must trust ProbatioVault won't access their data
4. **Breach mitigation**: If server compromised, data remains confidential

Traditional cloud storage (server-side encryption) means:
- Provider has access to decryption keys
- Provider can technically access plaintext
- Users must trust provider
- Data breach exposes plaintext

## Décision

We will implement **zero-knowledge architecture** with **client-side encryption**:
- All encryption/decryption happens in the client (app/browser)
- Master keys (K_master_user, K_vault_user, K_doc) never leave client
- Server stores only encrypted ciphertext (opaque blobs)
- Server cannot decrypt documents (no decryption keys)

Key hierarchy:
K_master_user (client only, derived from password) ↓ HKDF-SHA3-256 K_vault_user (client only) ↓ HKDF-SHA3-256 K_doc (client only) ↓ AES-256-GCM Encrypted document → Server (opaque) 
## Conséquences

### Positives
- **True zero-knowledge**: Server cannot access plaintext
- **RGPD compliant**: Data minimization, privacy by design
- **Breach resilient**: Compromised server doesn't expose plaintext
- **Trust**: Users don't need to trust ProbatioVault with their data
- **No liability**: ProbatioVault not responsible for plaintext
- **Regulatory**: Easier compliance (no plaintext processing)

### Négatives
- **No server-side features**: Cannot do full-text search, virus scan, OCR server-side
- **Key management complexity**: Users must manage their master keys
- **Lost key = lost data**: No password reset mechanism without user backup
- **Performance**: Encryption/decryption on client (mobile devices)
- **Client complexity**: More crypto logic in app

### Risques
- **User loses password**: Cannot recover documents
  - *Mitigation*: Strong password policy, key backup/recovery mechanism, user education
- **Client-side vulnerabilities**: XSS, malicious app version
  - *Mitigation*: CSP headers, code signing, app integrity checks
- **Compromised client**: Malware keylogger
  - *Mitigation*: Biometric auth (Face ID/Touch ID), user device security

## Alternatives considérées

### Alternative A: Server-side encryption
- **Description**: Encrypt at rest on server, server holds keys
- **Avantages**:
  - Simpler architecture
  - Password reset possible
  - Server-side features (search, virus scan)
- **Inconvénients**:
  - Server can access plaintext
  - Breach exposes data
  - Users must trust provider
  - RGPD concerns (data processor has access)
- **Raison du rejet**: Trust model, breach risk, competitive differentiation

### Alternative B: Hybrid (metadata unencrypted, content encrypted)
- **Description**: Encrypt document content, leave metadata (filename, date) in clear
- **Avantages**:
  - Server-side search on metadata
  - Easier organization/filtering
- **Inconvénients**:
  - Metadata can be sensitive (filenames reveal content)
  - Partial zero-knowledge (less trustworthy)
- **Raison du rejet**: Metadata leakage risk, prefer full zero-knowledge

### Alternative C: Homomorphic encryption
- **Description**: Encrypt data, allow computation on ciphertext
- **Avantages**:
  - Server-side features without decryption
  - Best of both worlds
- **Inconvénients**:
  - Immature technology (performance, libraries)
  - Extremely slow (impractical for production)
  - Complex implementation
- **Raison du rejet**: Not production-ready, overkill

## Références

- RGPD Art. 32: Security of processing
- Signal Protocol: https://signal.org/docs/
- ProtonMail Architecture: https://proton.me/security/zero-knowledge
- Tresorit Zero-Knowledge: https://tresorit.com/security
- PD-XX-specification.md: Zero-knowledge requirements

## Historique

| Date | Auteur | Changement |
|------|--------|------------|
| 2026-01-08 | Agent Architect | Création |
| 2026-01-09 | Loïc (Human) | Accepté |

ADR-003: Use of AWS CloudHSM for Master Key Operations

# ADR-003: Use of AWS CloudHSM for Master Key Operations

## Statut

ACCEPTÉ (2026-01-14)

## Contexte

ProbatioVault requires secure generation and storage of cryptographic keys for:
1. Organization master keys (K_master_org)
2. Vault organization keys (K_org_vault)
3. Proxy Re-Encryption (PRE) operations
4. Digital signatures (eIDAS)

Requirements:
- **FIPS 140-2 Level 3**: Regulatory requirement for cryptographic modules
- **Non-extractable keys**: Keys must not leave secure hardware
- **Tamper-resistant**: Physical security against attacks
- **Auditability**: Compliance logging

Software-based key storage (files, env vars) does not meet FIPS 140-2 Level 3.

## Décision

We will use **AWS CloudHSM (FIPS 140-2 Level 3)** for critical key operations:
- Generate K_master_org in HSM (non-extractable)
- Derive K_org_vault in HSM
- Perform PRE operations in HSM
- Store signature keys in HSM (eIDAS)

Keys stored in HSM:
- Organization master keys
- PRE re-encryption keys
- Signature private keys

Keys NOT in HSM (client-side):
- User master keys (K_master_user) - derived from password, client-side
- Document keys (K_doc) - derived client-side

## Conséquences

### Positives
- **FIPS 140-2 Level 3 certified**: Regulatory compliance
- **Tamper-resistant**: Hardware security module
- **Non-extractable keys**: Keys cannot be exfiltrated
- **AWS managed**: No hardware management burden
- **High availability**: Multi-AZ deployment
- **Auditability**: CloudTrail integration

### Négatives
- **Cost**: ~$1.20/hour (~$900/month) per HSM instance
- **Latency**: Network round-trip to HSM for each operation
- **AWS vendor lock-in**: Tied to AWS ecosystem
- **Complexity**: Additional infrastructure component

### Risques
- **AWS outage**: HSM unavailable → operations blocked
  - *Mitigation*: Multi-AZ deployment, fallback to cached derived keys
- **Cost escalation**: High volume of operations
  - *Mitigation*: Batch operations, cache derived keys when possible
- **Migration difficulty**: Hard to migrate away from AWS
  - *Mitigation*: Abstract HSM interface, document migration path

## Alternatives considérées

### Alternative A: Software-based key storage (AWS Secrets Manager)
- **Description**: Store keys in AWS Secrets Manager, encrypt with KMS
- **Avantages**:
  - Lower cost (~$0.40/secret/month)
  - Simpler architecture
  - Lower latency
- **Inconvénients**:
  - Not FIPS 140-2 Level 3 (only Level 2 via KMS)
  - Keys extractable (if AWS compromised)
  - Does not meet regulatory requirements
- **Raison du rejet**: FIPS 140-2 Level 3 required for probative value

### Alternative B: Self-hosted HSM (Thales, Utimaco)
- **Description**: Buy and manage physical HSM hardware
- **Avantages**:
  - Full control
  - No cloud dependency
  - Can choose vendor
- **Inconvénients**:
  - Expensive upfront cost ($10k-$50k per HSM)
  - Requires physical datacenter
  - Complex management (firmware updates, backups)
  - No high availability without multiple units
- **Raison du rejet**: Cost, complexity, prefer managed service

### Alternative C: AWS KMS
- **Description**: Use AWS Key Management Service
- **Avantages**:
  - Fully managed
  - Very low cost ($1/key/month)
  - Simple API
  - FIPS 140-2 Level 2
- **Inconvénients**:
  - Not Level 3 (only Level 2)
  - Less control (AWS manages keys)
  - Does not support PKCS#11 operations
- **Raison du rejet**: Insufficient security level (Level 2 vs Level 3)

## Références

- AWS CloudHSM: https://aws.amazon.com/cloudhsm/
- FIPS 140-2: https://csrc.nist.gov/publications/detail/fips/140/2/final
- CloudHSM Pricing: https://aws.amazon.com/cloudhsm/pricing/
- CloudHSM FIPS Certification #3254: https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/3254

## Historique

| Date | Auteur | Changement |
|------|--------|------------|
| 2026-01-14 | Agent Architect | Création |
| 2026-01-14 | Loïc (Human) | Accepté |

Principes d'écriture ADR

1. Immuabilité

Règle : Un ADR accepté ne se modifie jamais.

# Si la décision change :
# ❌ Ne pas modifier ADR-001
# ✅ Créer ADR-XXX qui REMPLACE ADR-001

# ADR-001
## Statut
REMPLACÉ par ADR-042 (2026-06-15)

# ADR-042
## Statut
ACCEPTÉ (2026-06-15)

## Contexte
ADR-001 chose SHA3-256, but we now need to support SHA-512 for...

2. Focus sur le "pourquoi"

# ❌ Mauvais ADR (décrit le "quoi")
## Décision
We use React Native for the mobile app.

# ✅ Bon ADR (explique le "pourquoi")
## Décision
We use React Native for the mobile app.

## Contexte
We need to support iOS and Android with:
- Limited budget (1 developer)
- Shared crypto logic with web (TypeScript)
- Fast iteration (startup)

React Native allows code sharing, TypeScript, and single team.

3. Considérer les alternatives

Obligation : Toujours lister au moins 2-3 alternatives avec raisons du rejet.

4. Être honnête sur les conséquences négatives

# ✅ Bon ADR (honnête)
## Conséquences

### Négatives
- Client-side encryption prevents server-side search
- Lost password = lost data (no recovery)
- Increased app complexity

### Risques
- User experience degraded (no search)
- Support burden (password reset requests)

Numérotation ADR

Convention

ADR-001, ADR-002, ADR-003, ...
  • Numérotation séquentielle
  • Pas de réutilisation de numéros
  • Gaps OK si ADR supprimé (rare)

Organisation fichiers

docs/architecture/adr/
  ├── README.md (index de tous les ADR)
  ├── ADR-001-sha3-256-hashing.md
  ├── ADR-002-zero-knowledge-architecture.md
  ├── ADR-003-aws-cloudhsm.md
  ├── ADR-004-typescript-backend.md
  └── template.md

Index README.md

# Architecture Decision Records

## Active

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [ADR-001](ADR-001-sha3-256-hashing.md) | SHA3-256 for Document Hashing | ACCEPTÉ | 2026-01-10 |
| [ADR-002](ADR-002-zero-knowledge-architecture.md) | Zero-Knowledge Architecture | ACCEPTÉ | 2026-01-08 |
| [ADR-003](ADR-003-aws-cloudhsm.md) | AWS CloudHSM for Master Keys | ACCEPTÉ | 2026-01-14 |

## Deprecated

| ADR | Title | Replaced By | Date |
|-----|-------|-------------|------|
| [ADR-999](ADR-999-old-decision.md) | Old Decision | ADR-042 | 2025-11-20 |

Statuts ADR

Statut Description Transition
PROPOSÉ ADR rédigé, en attente validation → ACCEPTÉ ou REJETÉ
ACCEPTÉ Décision validée et appliquée → DÉPRÉCIÉ ou REMPLACÉ
REJETÉ Proposition rejetée (gardé pour historique) Final
DÉPRÉCIÉ Plus recommandé mais toujours en production → REMPLACÉ
REMPLACÉ Remplacé par un nouvel ADR Final (pointeur vers nouveau)

Checklist ADR

Avant de soumettre un ADR

  • Numéro ADR unique attribué
  • Titre clair et descriptif
  • Statut défini (PROPOSÉ au départ)
  • Contexte explique le problème à résoudre
  • Décision claire et sans ambiguïté
  • Au moins 2-3 alternatives considérées
  • Conséquences positives ET négatives listées
  • Risques identifiés avec mitigations
  • Références complètes
  • Historique avec date/auteur

Avant d'accepter un ADR

  • Validation humaine (décideur)
  • Alternatives sérieusement évaluées
  • Conséquences comprises et acceptées
  • Implémentation possible (faisabilité validée)
  • Mise à jour statut → ACCEPTÉ
  • Ajout dans index README.md

Escalade

Escalader vers PMO + humain décideur si : - Décision architecturale majeure (impact système complet) - Choix entre alternatives équivalentes (arbitrage nécessaire) - Décision avec conséquences financières importantes - Contradiction avec ADR existants - Désaccord entre agents sur la décision

Références

  • MADR: https://adr.github.io/madr/
  • ADR Tools: https://github.com/npryce/adr-tools
  • Thoughtworks ADR: https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records

Historique

Version Date Changement
1.0.0 2026-01-14 Création initiale