Refresh token, idempotence et notifications : l'API Node.js d'une application mobile

-- sql/mobile.sql : les tables qu'ajoute l'application mobile (MySQL 8.4)
CREATE TABLE jeton_rafraichissement (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  id_utilisateur INT      NOT NULL,
  famille        CHAR(36) NOT NULL,              -- la même pour tous les jetons nés d'une connexion
  empreinte      CHAR(64) NOT NULL UNIQUE,       -- SHA-256 du jeton, jamais le jeton lui-même
  expire_le      DATETIME NOT NULL,              -- en UTC
  utilise_le     DATETIME NULL,                  -- rempli à la rotation : un jeton ne sert qu'une fois
  revoque        BOOLEAN  NOT NULL DEFAULT FALSE,
  INDEX idx_famille (famille),
  CONSTRAINT fk_jeton_utilisateur FOREIGN KEY (id_utilisateur) REFERENCES utilisateur (id) ON DELETE CASCADE
) ENGINE = InnoDB;

CREATE TABLE cle_idempotence (
  id_utilisateur INT         NOT NULL,
  cle            VARCHAR(64) NOT NULL,
  empreinte      CHAR(64)    NOT NULL,           -- SHA-256 de la requête : même clé, même contenu
  statut         SMALLINT    NULL,               -- NULL tant que la première requête est en cours
  reponse        TEXT        NULL,               -- le corps JSON renvoyé la première fois
  cree_le        DATETIME    NOT NULL,           -- en UTC ; une clé vaut 24 heures
  PRIMARY KEY (id_utilisateur, cle),
  CONSTRAINT fk_cle_utilisateur FOREIGN KEY (id_utilisateur) REFERENCES utilisateur (id) ON DELETE CASCADE
) ENGINE = InnoDB;

CREATE TABLE appareil (
  jeton_push     VARCHAR(255) PRIMARY KEY,       -- ExponentPushToken[…]
  id_utilisateur INT          NOT NULL,
  plateforme     ENUM('android', 'ios') NOT NULL,
  maj_le         DATETIME     NOT NULL,
  CONSTRAINT fk_appareil_utilisateur FOREIGN KEY (id_utilisateur) REFERENCES utilisateur (id) ON DELETE CASCADE
) ENGINE = InnoDB;

mysql -u root -p applifrais < sql/mobile.sql

// src/services/jetons.service.js
import { createHash, randomBytes, randomUUID } from 'node:crypto';
import jwt from 'jsonwebtoken';
import { config } from '../config.js';
import { pool } from '../db.js';
import { ErreurApi } from '../erreurs.js';

export const DUREE_ACCES = 15 * 60; // secondes
const DUREE_RAFRAICHISSEMENT_MS = 30 * 24 * 60 * 60 * 1000; // 30 jours

const empreinte = (jeton) => createHash('sha256').update(jeton).digest('hex');
// Date au format DATETIME de MySQL, en UTC : '2026-11-02 08:15:00'
export const dateSql = (ms = Date.now()) => new Date(ms).toISOString().slice(0, 19).replace('T', ' ');
const sessionExpiree = () => new ErreurApi(401, 'session-expiree', 'Session expirée', 'Reconnecte-toi.');

export function signerAcces(utilisateur) {
  return jwt.sign({ role: utilisateur.role }, config.jwtSecret, {
    subject: String(utilisateur.id),
    expiresIn: DUREE_ACCES,
    algorithm: 'HS256',
  });
}

// Un jeton aléatoire de 256 bits ; la base n'en garde que l'empreinte SHA-256.
export async function creerRafraichissement(idUtilisateur, famille = randomUUID()) {
  const jeton = randomBytes(32).toString('base64url');
  await pool.execute(
    'INSERT INTO jeton_rafraichissement (id_utilisateur, famille, empreinte, expire_le) VALUES (?, ?, ?, ?)',
    [idUtilisateur, famille, empreinte(jeton), dateSql(Date.now() + DUREE_RAFRAICHISSEMENT_MS)],
  );
  return jeton;
}

// Rotation : le jeton présenté est consommé, une nouvelle paire est émise dans la même famille.
export async function tourner(jeton) {
  const [[ligne]] = await pool.execute(
    'SELECT id, id_utilisateur, famille, expire_le, revoque FROM jeton_rafraichissement WHERE empreinte = ?',
    [empreinte(jeton)],
  );
  if (!ligne || ligne.revoque || ligne.expire_le < dateSql()) throw sessionExpiree();

  // « AND utilise_le IS NULL » : un jeton ne sert qu'une fois, même si deux requêtes arrivent ensemble.
  const [resultat] = await pool.execute(
    'UPDATE jeton_rafraichissement SET utilise_le = ? WHERE id = ? AND utilise_le IS NULL',
    [dateSql(), ligne.id],
  );
  if (resultat.affectedRows === 0) {
    // Jeton déjà utilisé : il a peut-être été volé. Toute la session (la famille) est révoquée.
    await pool.execute('UPDATE jeton_rafraichissement SET revoque = TRUE WHERE famille = ?', [ligne.famille]);
    throw new ErreurApi(401, 'session-revoquee', 'Session révoquée', 'Jeton déjà utilisé : reconnecte-toi.');
  }

  const [[utilisateur]] = await pool.execute('SELECT id, role FROM utilisateur WHERE id = ?', [ligne.id_utilisateur]);
  return {
    accessToken: signerAcces(utilisateur),
    refreshToken: await creerRafraichissement(utilisateur.id, ligne.famille),
  };
}

// Déconnexion : toute la famille du jeton est révoquée ; un jeton inconnu ne change rien.
export async function revoquer(jeton) {
  const [[ligne]] = await pool.execute(
    'SELECT famille FROM jeton_rafraichissement WHERE empreinte = ?',
    [empreinte(jeton)],
  );
  if (ligne) await pool.execute('UPDATE jeton_rafraichissement SET revoque = TRUE WHERE famille = ?', [ligne.famille]);
}

// src/controllers/auth.controller.js (extraits)
import { creerRafraichissement, DUREE_ACCES, revoquer, signerAcces, tourner } from '../services/jetons.service.js';

export async function connexion(req, res) {
  // … vérification du login et du mot de passe, inchangée …
  const accessToken = signerAcces(utilisateur);
  const refreshToken = await creerRafraichissement(utilisateur.id); // une nouvelle famille
  req.log.info({ utilisateurId: utilisateur.id }, 'Connexion réussie');
  res.set('Cache-Control', 'no-store').json({ accessToken, tokenType: 'Bearer', expiresIn: DUREE_ACCES, refreshToken });
}

export async function rafraichissement(req, res) {
  const { accessToken, refreshToken } = await tourner(req.valide.body.refreshToken);
  res.set('Cache-Control', 'no-store').json({ accessToken, tokenType: 'Bearer', expiresIn: DUREE_ACCES, refreshToken });
}

export async function deconnexion(req, res) {
  await revoquer(req.valide.body.refreshToken);
  res.sendStatus(204); // même réponse pour un jeton inconnu : il n'y a rien à apprendre ici
}

// src/schemas/fiches.schemas.js (ajout)
export const schemaJetonRafraichissement = z.strictObject({
  refreshToken: z.string().min(20).max(100),
});

// src/routes/auth.routes.js (ajout)
routeurAuth.post('/rafraichissement', valider({ body: schemaJetonRafraichissement }), rafraichissement);
routeurAuth.post('/deconnexion', valider({ body: schemaJetonRafraichissement }), deconnexion);

// src/middlewares/idempotence.js
import { createHash } from 'node:crypto';
import { pool } from '../db.js';
import { ErreurApi } from '../erreurs.js';
import { dateSql } from '../services/jetons.service.js';

const DUREE_CLE_MS = 24 * 60 * 60 * 1000; // une clé vaut 24 heures

// Même clé et même requête : la réponse d'origine est rejouée, rien n'est créé une deuxième fois.
// À placer après authentifier et valider.
export async function idempotence(req, res, next) {
  const cle = req.get('Idempotency-Key');
  if (cle === undefined) return next(); // l'en-tête est facultatif
  if (!/^[\w-]{8,64}$/.test(cle)) {
    throw new ErreurApi(400, 'cle-idempotence-invalide', "Clé d'idempotence invalide",
      'De 8 à 64 caractères : lettres, chiffres, tirets.');
  }
  const idUtilisateur = req.utilisateur.id;
  const empreinte = createHash('sha256')
    .update(`${req.method} ${req.originalUrl} ${JSON.stringify(req.valide.body)}`)
    .digest('hex');

  await pool.execute(
    'DELETE FROM cle_idempotence WHERE id_utilisateur = ? AND cle = ? AND cree_le < ?',
    [idUtilisateur, cle, dateSql(Date.now() - DUREE_CLE_MS)],
  );
  try {
    await pool.execute(
      'INSERT INTO cle_idempotence (id_utilisateur, cle, empreinte, cree_le) VALUES (?, ?, ?, ?)',
      [idUtilisateur, cle, empreinte, dateSql()],
    );
  } catch (erreur) {
    if (erreur.code !== 'ER_DUP_ENTRY') throw erreur;
    // La clé est connue : c'est un renvoi.
    const [[connue]] = await pool.execute(
      'SELECT empreinte, statut, reponse FROM cle_idempotence WHERE id_utilisateur = ? AND cle = ?',
      [idUtilisateur, cle],
    );
    if (connue.empreinte !== empreinte) {
      throw new ErreurApi(422, 'cle-deja-utilisee', 'Clé déjà utilisée', 'Cette clé a servi pour une autre requête.');
    }
    if (connue.statut === null) {
      throw new ErreurApi(409, 'requete-en-cours', 'Requête en cours', 'La même requête est encore en traitement.');
    }
    return res.status(connue.statut).json(JSON.parse(connue.reponse));
  }

  // Première fois : la route travaille ; sa réponse est enregistrée avant de partir.
  const envoyerJson = res.json.bind(res);
  res.json = async (corps) => {
    try {
      if (res.statusCode < 300) {
        await pool.execute(
          'UPDATE cle_idempotence SET statut = ?, reponse = ? WHERE id_utilisateur = ? AND cle = ?',
          [res.statusCode, JSON.stringify(corps), idUtilisateur, cle],
        );
      } else {
        // Refus (404, 409, 422…) : la clé est libérée, le client pourra renvoyer une requête corrigée.
        await pool.execute('DELETE FROM cle_idempotence WHERE id_utilisateur = ? AND cle = ?', [idUtilisateur, cle]);
      }
    } catch (erreur) {
      req.log.error(erreur, "Clé d'idempotence non enregistrée");
    }
    return envoyerJson(corps);
  };
  next();
}

// src/routes/fiches.routes.js : le middleware se place après la validation
routeurFiches.post('/:id/frais-hors-forfait', exigerRole('visiteur'),
  valider({ params: schemaId, body: schemaFraisHorsForfait }), idempotence, fiches.ajouterFraisHorsForfait);

// src/schemas/fiches.schemas.js (ajout)
export const schemaAppareil = z.strictObject({
  jetonPush: z.string().max(255).regex(/^Expo(nent)?PushToken\[.+\]$/, 'Jeton Expo attendu'),
  plateforme: z.enum(['android', 'ios']),
});

// src/routes/appareils.routes.js
import { Router } from 'express';
import { pool } from '../db.js';
import { authentifier } from '../middlewares/authentifier.js';
import { exigerRole } from '../middlewares/autoriser.js';
import { valider } from '../middlewares/valider.js';
import { schemaAppareil } from '../schemas/fiches.schemas.js';
import { dateSql } from '../services/jetons.service.js';

export const routeurAppareils = Router();

routeurAppareils.use(authentifier, exigerRole('visiteur'));

// PUT : enregistrer deux fois le même jeton ne crée pas deux lignes.
routeurAppareils.put('/', valider({ body: schemaAppareil }), async (req, res) => {
  const { jetonPush, plateforme } = req.valide.body;
  // Le visiteur vient du jeton d'accès, jamais du corps. REPLACE : un téléphone prêté change de propriétaire.
  await pool.execute(
    'REPLACE INTO appareil (jeton_push, id_utilisateur, plateforme, maj_le) VALUES (?, ?, ?, ?)',
    [jetonPush, req.utilisateur.id, plateforme, dateSql()],
  );
  res.sendStatus(204);
});

// src/app.js (ajout, avec les autres routeurs)
app.use('/v1/appareils', routeurAppareils);