Guide pratique

Intégration rapide : le guide universel

Intégrez le chiffrement MAFATE dans n'importe quelle application en 15 minutes. Ce guide couvre tous les frameworks populaires avec des middlewares prêts à l'emploi.

1. Le pattern universel

Quelle que soit la stack, l'intégration MAFATE suit toujours le même schéma en 3 étapes.

1
Initialiser le client MAFATE
Une seule instance partagée avec votre clé API, en singleton ou via injection de dépendance.
2
Chiffrer avant INSERT / UPDATE
Chaque champ PII est chiffré en local avec la clé dédiée à son domaine, puis stocké sous forme d'enveloppe complète : ciphertext, wrapped_key, iv, key_id, key_version, envelope_version.
3
Déchiffrer après SELECT
L’enveloppe stockée en base est déchiffrée à la lecture, uniquement quand le clair est vraiment nécessaire. Un seul appel réseau, pour désemballer la clé de données.

Bonne pratique : middleware de chiffrement

Plutôt que d'appeler mafate.encryptLocal() dans chaque handler, encapsulez la logique dans un middleware ou un hook. Vos handlers restent propres et le chiffrement devient transparent.

2. Middleware par langage

Exemples complets de middleware pour chaque langage. Copiez et adaptez selon votre stack.

import { Mafate } from '@mafate/sdk'

const mafate = new Mafate({ apiKey: process.env.MAFATE_API_KEY })
const KEY_ID = process.env.MAFATE_KEY_ID! // UUID rendu par POST /v1/keys

// Middleware generique : chiffre EN LOCAL les champs listes avant le handler.
// Le clair ne quitte pas ce processus ; seule la cle de donnees part se faire
// emballer par MAFATE.
const encryptFields = (fields: string[]) => async (req, res, next) => {
  try {
    for (const field of fields) {
      if (req.body[field] !== undefined) {
        // L'enveloppe rendue est un objet a six champs. Stockez-la ENTIERE :
        // il en manque un seul et la donnee est perdue.
        req.body[field] = await mafate.encryptLocal(req.body[field], KEY_ID)
      }
    }
    next()
  } catch (err) {
    next(err)
  }
}

app.post(
  '/api/users',
  encryptFields(['email', 'phone', 'address', 'firstName', 'lastName']),
  createUser
)

app.put('/api/users/:id', encryptFields(['email', 'phone', 'address']), updateUser)

3. Configuration par environnement

Utilisez des clés différentes pour chaque environnement. Ne partagez jamais une clé entre dev et prod.

# ⚠️ MAFATE_KEY_ID est l'UUID rendu par POST /v1/keys, pas un nom lisible.
# Le nom que vous donnez a la creation sert a vous y retrouver dans le
# tableau de bord ; il ne resout aucune route.

# .env.development
MAFATE_API_KEY=eaas_sk_EXEMPLE_NON_VALIDE
MAFATE_KEY_ID=1f0c4a7e-2b91-4d3a-8c56-0e7d9a1b2c3d
DATABASE_URL=postgres://localhost/myapp_dev

# .env.staging
MAFATE_API_KEY=eaas_sk_EXEMPLE_STAGING_NON_VALIDE
MAFATE_KEY_ID=5b8e2c19-7a04-4f61-9d2e-3c7a5b1908fd
DATABASE_URL=postgres://staging-db/myapp_staging

# .env.production
MAFATE_API_KEY=eaas_sk_EXEMPLE_PROD_NON_VALIDE
MAFATE_KEY_ID=7c9e6679-7425-40de-944b-e07fc1f90ae7
DATABASE_URL=postgres://prod-db/myapp_prod

# Toutes les cles portent le meme prefixe eaas_sk_ : le serveur n'a aucune
# notion d'environnement. C'est le LOCATAIRE qui separe vos environnements,
# pas un suffixe dans la cle.

4. Vérification

Après intégration, vérifiez que le chiffrement fonctionne correctement : le ciphertext est bien stocké en base, et le déchiffrement retourne la valeur originale.

import { Mafate } from '@mafate/sdk'

// Verifier que la chaine complete fonctionne, de bout en bout.
async function verifyCrypto() {
  const mafate = new Mafate({ apiKey: process.env.MAFATE_API_KEY })
  const KEY_ID = process.env.MAFATE_KEY_ID!
  const original = '[email protected]'

  // 1. Chiffrer en local
  const env = await mafate.encryptLocal(original, KEY_ID)
  console.log('Enveloppe :', JSON.stringify(env))

  // 2. Dechiffrer en local
  const clair = await mafate.decryptLocalToString(env)

  // 3. Verifier l'aller-retour
  console.assert(clair === original, 'ERREUR : decryptLocal(encryptLocal(x)) !== x')

  // 4. Verifier ce qui est REELLEMENT en base : les six champs.
  const row = await db.query('SELECT email FROM users ORDER BY id DESC LIMIT 1')
  const stocke = JSON.parse(row.rows[0].email)
  for (const champ of ['ciphertext', 'wrapped_key', 'iv', 'key_id', 'key_version', 'envelope_version']) {
    console.assert(champ in stocke, `champ ${champ} absent : la donnee sera indechiffrable`)
  }

  // 5. Et surtout : verifier que le clair n'y est PAS.
  console.assert(!row.rows[0].email.includes('@example.com'), 'PII en clair en base')
  console.log('Verification OK')
}

Bonnes pratiques Intégration ORM