Exiger un code à usage unique

Pour un transfert sensible, le mot de passe ne suffit pas toujours : il peut être transmis par erreur, partagé ou intercepté. Le champ require_totp ajoute une seconde barrière au moment du téléchargement : un code à usage unique à six chiffres, qui change toutes les 30 secondes et que seul le détenteur de l'application d'authentification du destinataire peut produire. Même si le lien et le mot de passe fuitent, le fichier reste inaccessible sans ce code. Cette page explique comment activer l'exigence à la création du transfert, comment le destinataire fournit son code au téléchargement, et comment cette protection se combine avec le mot de passe.

Activer l'exigence à la création

Passez require_totp: true dans le corps de POST /v1/transfers. La réponse contient alors un champ totp_secret : c'est le secret à provisionner dans l'application d'authentification du destinataire. Ce secret n'est renvoyé qu'une seule fois, à la création. Transmettez-le au destinataire par un canal distinct du lien de partage, puis ne le conservez pas.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const result = await coffrify.transfers.create({
  files: [{ name: 'rapport-conseil.pdf', size: 482113, mime_type: 'application/pdf' }],
  transfer_title: 'Rapport au conseil T2',
  recipient: 'jean.martin@exemple.fr',
  expires_in_hours: 48,
  max_downloads: 3,
  require_totp: true,
});
 
// Affiché UNE seule fois : à transmettre au destinataire hors du lien.
console.log('Secret à provisionner :', result.totp_secret);
console.log('Lien de partage      :', result.share_url);

Téléversez ensuite chaque fichier via les upload_urls renvoyées (requête PUT), comme pour tout transfert. Une fois le téléversement terminé, le lien share_url est actif et le code à usage unique sera exigé à chaque téléchargement.

Provisionner le secret côté destinataire

Le destinataire ajoute le totp_secret à son application d'authentification. Deux options : saisir le secret manuellement, ou scanner un QR code que vous construisez à partir de l'URI standard otpauth. Le code généré est un TOTP conforme à la RFC 6238 : six chiffres, renouvelés toutes les 30 secondes.

otpauth://totp/Coffrify:rapport-conseil.pdf?secret=LE_TOTP_SECRET&issuer=Coffrify&digits=6&period=30

Flux côté destinataire au téléchargement

À l'ouverture du lien, le destinataire est invité à saisir le code à six chiffres affiché par son application. Le code est transmis dans le corps de la requête d'accès, via le champ totp. Tant qu'aucun code valide n'est fourni, aucune URL de téléchargement n'est délivrée.

// Étape 1 : sans code, l'accès est refusé et indique qu'un code est requis.
let res = await fetch(`https://files.coffrify.com/${shortCode}/access`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
// res.status === 401, corps : { error: 'TOTP required', requireTotp: true }
 
// Étape 2 : avec le code à six chiffres saisi par le destinataire.
res = await fetch(`https://files.coffrify.com/${shortCode}/access`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ totp: '418207' }),
});
const data = await res.json();
// res.status === 200 : data.files contient les URL signées (valables 60 s).

En cas de succès, la réponse renvoie la liste des fichiers avec des URL de téléchargement signées à durée de vie courte (60 secondes), à utiliser immédiatement. Le compteur de téléchargements n'est débité qu'une fois tous les contrôles franchis, code à usage unique compris.

Réponses possibles à la validation du code

Un code refusé ne consomme pas de téléchargement : le destinataire peut le ressaisir. Présentez un message clair invitant à vérifier que l'heure de l'appareil est synchronisée et à attendre, si besoin, le code suivant.

Articulation avec le mot de passe

Le code à usage unique et le mot de passe sont indépendants et cumulables. Pour exiger les deux, fournissez password et require_totp: true à la création. Au téléchargement, le destinataire envoie alors les deux champs, password et totp, dans la même requête. Le mot de passe est vérifié en premier : tant qu'il est absent ou incorrect, le code à usage unique n'est pas évalué.

const result = await coffrify.transfers.create({
  files: [{ name: 'due-diligence.zip', size: 10485760, mime_type: 'application/zip' }],
  transfer_title: 'Data room - due diligence',
  password: 'phrase-secrete-robuste',
  require_totp: true,
  expires_in_hours: 24,
  max_downloads: 1,
});
// result.totp_secret : à provisionner. Le mot de passe se transmet à part.

Lorsque le mot de passe est requis mais absent, la réponse 401 inclut un objet meta dont le champ requireTotp indique si un code à usage unique sera également demandé. Un client peut s'appuyer dessus pour afficher d'emblée les deux champs au destinataire et lui éviter un aller-retour.