Gestion des clés

1. Structure des clés recommandée

Utilisez un schéma de nommage cohérent : {environnement}-{domaine}-{type}. Une clé par type de données sensible permet une rotation et une révocation indépendantes.

// Structure de clés recommandée par environnement et domaine
//
// Production
production-users-pii          // Données personnelles utilisateurs
production-users-address       // Adresses (séparées pour rotation indépendante)
production-payment-iban        // IBANs
production-payment-cards       // Tokens carte
production-payment-transactions // Montants de transaction
production-documents           // Fichiers & documents sensibles

// Staging (clés séparées, isolation totale)
staging-users-pii
staging-payment-iban

// Tests (jamais de vraies données)
test-data-mock

// Santé (nomenclature réglementaire)
hds-pht-clinic-paris           // Identité patients, clinique Paris
hds-phi-clinic-paris           // Données médicales, clinique Paris

2. Créer une clé

import { Mafate } from '@mafate/sdk'

const mafate = new Mafate({ apiKey: process.env.MAFATE_API_KEY })

// `name` est le seul champ obligatoire. Il n'existe pas de champ
// `description`, et l'identifiant n'est pas choisi par vous.
const key = await mafate.keys.create({
  name: 'production-users-pii',
  algorithm: 'AES-256-GCM',
})

console.log(key)
// {
//   id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',   <- L'UUID A CONSERVER
//   name: 'production-users-pii',
//   algorithm: 'AES-256-GCM',
//   status: 'active',
//   current_version: 1,
//   created_at: '2026-01-15T10:00:00Z'
// }

// ⚠️ C'est `id` qui s'ecrit ensuite dans les chemins et dans le champ
// key_id des operations de chiffrement. Le nom ne resout aucune route.

3. Rotation des clés

La rotation crée une nouvelle version de la clé. Les ciphertexts existants (versions antérieures) restent déchiffrables : aucune migration de données n'est requise. Les nouveaux chiffrements utilisent automatiquement la dernière version.

// Rotation manuelle. L'argument est l'UUID, jamais le nom.
const key = await mafate.keys.rotate(KEY_ID)

console.log(key.current_version) // 3
// ⛔ Il n'existe ni previousVersion, ni newVersion, ni rotatedAt dans la
// reponse : elle rend l'objet cle mis a jour.

// Les enveloppes produites avec les versions 1 et 2 restent dechiffrables :
// unwrap lit la version dans le jeton wrapped_key.

4. Permissions par clé API

Créez des clés API avec les permissions minimales requises. Par exemple, le service de lecture d'une application ne doit avoir que le droit de déchiffrer, pas de chiffrer ou de gérer les clés.

// Clé API pour le service de lecture (déchiffrement seulement)
{
  "name": "service-lecture-prod",
  "permissions": ["decrypt"],
  "keyIds": ["production-users-pii", "production-users-address"],
  "ipWhitelist": ["10.0.1.0/24"]
}

// Clé API pour le service d'inscription (chiffrement seulement)
{
  "name": "service-inscription-prod",
  "permissions": ["encrypt"],
  "keyIds": ["production-users-pii", "production-users-address"]
}

// Clé API pour le pipeline de rotation (rotation + audit)
{
  "name": "rotation-service",
  "permissions": ["keys:rotate", "audit:read"],
  "keyIds": ["*"]
}

5. Bonnes pratiques