MDTrust
SwaggerDashboard

Documentation de l’API MDTrust

MDTrust est une API REST de Confiance Numérique (TaaS). Elle permet aux entreprises de vérifier l’authenticité des communications numériques et de certifier des liens en temps réel avec une latence garantie inférieure à 150 ms.

1 000 requêtes Sandbox offertes dès l’inscriptionCréez votre compte B2B pour obtenir vos clés d’API secrètes et publiques de test.

Authentification & Séparation des Clés

Toutes les requêtes vers l'API MDTrust s'authentifient via l'en-tête standard Authorization: Bearer <CLE_API>.

Clés Secrètes Serveur (sk)md_test_sk_... / md_live_sk_...

Utilisées pour les appels backend critiques et la certification dynamique de liens (/v1/certify).

Clés Publiques Frontend (pk)md_test_pk_... / md_live_pk_...

Utilisées dans les applications mobiles Flutter / React Native et applications web pour la vérification simple (/v1/verify).

SDKs Clients Développeurs Officiels

Recommandé en Production

Pour une intégration rapide et sécurisée sans manipuler manuellement les en-têtes HTTP, timeouts ou comparaisons cryptographiques de webhooks, utilisez les bibliothèques officielles MDTrust prêtes à l'emploi :

SDK Python (mdtrust)v2.0.0

Clients synchrone (MDTrust) et asynchrone (AsyncMDTrust) pour FastAPI et Django. Typage complet et validation HMAC-SHA256 intégrée.

pip install mdtrust
SDK Node.js & TypeScript (@mdtrust/sdk)v2.0.0

Zéro dépendance externe (utilise fetch et crypto natifs). Compatible Express, Next.js, NestJS et Fastify.

npm install @mdtrust/sdk
SDK Flutter & Dart (mdtrust)v2.0.0

Multiplateforme iOS, Android, Web et Desktop. Support complet de la vérification de flux avec analyse d'homoglyphes, démasquage automatique et vérification de webhooks.

flutter pub add mdtrust
SDK Java (com.mdtrust:mdtrust-sdk)v2.0.0

Compatible Java 17+ (Spring Boot, Quarkus, Micronaut). Zéro dépendance externe, client HttpClient HTTP/2 natif, records typés et vérificateur HMAC.

implementation 'com.mdtrust:mdtrust-sdk:2.0.0'

Exemples d’Intégration Prêts à l’Emploi

Copiez et collez directement ces snippets fonctionnels dans votre environnement de production :

# Installation : pip install mdtrust
from mdtrust import MDTrust

# 1. Initialiser le client officiel
client = MDTrust(api_key="md_live_sk_VOTRE_CLE_SECRETE")

# 2. Vérifier un lien entrant (/v1/verify)
result = client.verify(
    target_url="https://paiement.service-client.com/pay/4920",
    channel="sms",
    sender_id="SERVICE_CLIENT"
)

if result.is_safe:
    print("Succès : Lien authentique certifié par", result.certified_institution.name)
elif result.is_blocked:
    print(f"Danger [{result.verdict}] : {result.recommendation.user_message}")

# 3. Certifier dynamiquement un lien sortant (/v1/certify)
cert = client.certify(
    target_url="https://mon-application.ci/recu/trx_908234",
    channel="sms",
    ttl_seconds=3600 # 1 heure
)
print("URL certifiée :", cert.certified_url)

# 4. Valider la signature HMAC-SHA256 d'un Webhook entrant
is_valid = MDTrust.verify_webhook_signature(
    payload=raw_webhook_body,
    signature=headers.get("X-MDTrust-Signature"),
    secret="whsec_VOTRE_SECRET_WEBHOOK"
)

Matrice des verdicts et score de confiance externe

MDTrust sépare formellement la preuve institutionnelle déclarée (Cas A) de l'évaluation probabiliste par sondes externes (Cas B lorsque le lien est inconnu).

Cas A

Certification institutionnelle officielle (Registre MDTrust)

Statut / VerdictActionPreuve techniqueMessage recommandé
CERTIFIÉ (CERTIFIED)ALLOWPreuve institutionnelle valide & active dans le registre officiel MDTrust (Audit KYB + DNS).Communication certifiée par l'institution. Vous pouvez poursuivre en toute confiance.
INCOHÉRENT (INCONSISTENT)BLOCKInstitution identifiée mais divergence critique (sous-domaine non autorisé, token expiré).Attention, ce lien ne correspond pas aux règles d'émission de l'institution.
Cas B

Lien inconnu de la base : Barème du score de confiance externe

Lorsque le lien est inconnu de la base, MDTrust ne peut pas certifier directement son authenticité. Un score de confiance est alors calculé à partir de sources externes : modèles de langage (LLM), API de réputation et fournisseurs tiers (Providers).

Score de confianceVerdict officielAction APIInterprétation recommandée
> 80 %Plutôt bon, mais prudence recommandéeALLOWAucun signal malveillant externe. L'usager peut naviguer mais l'émetteur n'est pas garanti à 100%.
60 % à 80 %VigilanceWARNIndicateurs globalement neutres mais garanties modérées. Appel à la prudence.
45 % à 60 %AttentionWARNSignaux atypiques détectés (absence de certificat étendu, jeunesse du domaine). Éviter la saisie d'identifiants.
0 % à 45 %Non recommandéBLOCKRisque élevé de phishing, usurpation ou escroquerie. Blocage recommandé de l'accès.

Moteur de dé-cloisonnement de redirections M → 1

Les attaquants comme les applications légitimes utilisent fréquemment des raccourcisseurs d'URL (bit.ly, tinyurl, t.co) ou des paramètres de redirection imbriqués (?url=..., ?redirect=...).

Le moteur MDTrust résout tous les cas de figure de liens réduits vers le lien final de redirection (M → 1) en appliquant une validation anti-SSRF stricte à chaque saut et en évaluant la destination terminale.

Analyse comparative : MDTrust face aux solutions du marché

A. Vérificateurs de liens suspectsCheckPhish, URLVoid, EmailVeritas

Répondent à : « Ce lien est-il dangereux ? » mais ne répondent pas à : « Ce lien provient-il réellement de ma banque ? ».

B. Détecteurs d'arnaques IATrustyn, ArnaqueScan

Répondent à : « Cela ressemble-t-il à une arnaque ? » mais ne disposent pas d'un mécanisme où l'institution certifie elle-même ses flux.

C. Authentification de l'expéditeurSinch, Telesign

Valident le numéro de téléphone, le SMS OTP et le MFA, mais pas la vérification du lien reçu.

Protection Anti-Quishing (QR Codes Malveillants)

Sécurisation des vecteurs physiques, imprimés et numériques
Standard MDTrust v2.0

Qu'est-ce que le Quishing et pourquoi les filtres classiques échouent ?

Le Quishing (QR Phishing) consiste à détourner la confiance accordée aux codes QR pour tromper les utilisateurs. Les attaquants collent de faux autocollants QR sur des parcmètres, des bornes de recharge électrique, des tables de restaurant, ou insèrent des images QR dans des emails d'hameçonnage.

Les passerelles de messagerie traditionnelles (Secure Email Gateways) échouent souvent car le lien malveillant n'est pas présent sous forme de texte, mais encapsulé dans une matrice de pixels. L'API MDTrust résout ce problème en fournissant une infrastructure de certification et de vérification en temps réel dédiée aux QR codes.

1

Décodage Client Local

L'application web ou mobile lit la matrice QR via caméra ou image en local (ex: jsQR ou mobile_scanner). Aucune image brute n'est envoyée sur le réseau.

2

Appel API "qr_code"

L'URL décodée est envoyée à /v1/verify avec le paramètre channel: "qr_code". Le moteur vérifie l'institution et démasque les redirections courtes.

3

Décision & Alerte SOC

Si l'action est ALLOW, le paiement ou la navigation s'ouvre. Si l'action est BLOCK, un écran rouge stoppe l'usager et un webhook alerte la marque usurpée.

Mise en place Côté FrontendWeb & Mobile

Intégrez la caméra ou l'upload d'image dans votre application, puis déléguez la vérification à MDTrust avec votre clé publique (md_live_pk_...) sans exposer de secret.

  1. Installez le décodeur : npm i jsqr (Web) ou mobile_scanner (Flutter).
  2. Dès qu'une trame contient une URL, transmettez-la à /v1/verify.
  3. Spécifiez obligatoirement "channel": "qr_code" pour activer les règles de tolérance Quishing.
  4. Interceptez le verdict avant d'autoriser le navigateur à charger la page.
Exemple complet disponible dans les onglets ci-dessus :
Mise en place Côté BackendAPI & Microservices

Si vous centralisez les scans sur vos propres serveurs (ex: passerelle de paiement scannée en caisse, bornes interactives), utilisez votre clé secrète (md_live_sk_...).

  1. Effectuez un appel POST /v1/verify ou utilisez les SDKs Python / Node / Java.
  2. Renseignez le contexte client : user_ip et channel: "qr_code".
  3. Le moteur MDTrust analyse les homoglyphes, le certificat SSL et résout les URL raccourcies protégées par redirection anti-SSRF.
  4. En cas d'usurpation avérée, MDTrust dispatche automatiquement un Webhook TYPOSQUATTING_ALERT vers l'entreprise ciblée.
Exemple complet disponible dans les onglets ci-dessus :

Référence Complète des Endpoints

Détail exhaustif des paramètres et réponses des endpoints de production MDTrust :

POST/v1/verify
Authentification requise (Bearer sk ou pk) • Latence < 150 ms

Analyse l'authenticité d'un lien ou d'une communication entrante en vérifiant les registres institutionnels, la réputation DNS/SSL, les attaques par homoglyphes et le Quishing.

Champ BodyTypeRequisDescription
target_urlstringOuiURL ou lien extrait d'un SMS, WhatsApp, Email ou QR Code.
channelstringNon (défaut: "web")Canal source : qr_code, sms, whatsapp, email, mobile_app, web.
client_contextobjectNonMétadonnées d'analyse : { sender_id, user_ip, user_agent }.
POST/v1/certify
Authentification Clé Secrète requise (Bearer sk)

Certifie dynamiquement une URL transactionnelle ou éphémère (ex: lien de paiement sécurisé, code OTP de validation bancaire) avant de l'envoyer à un client.

Champ BodyTypeRequisDescription
target_urlstringOuiURL exacte à certifier dans le registre MDTrust.
ttl_secondsintegerNon (défaut: 86400s)Durée de vie du certificat (ex: 900 pour un lien OTP valable 15 minutes).
channelstringNonCanal prévu d'émission (sms, qr_code, whatsapp, email).
POST/api/public/scan
Accès Public Citoyen • Plafonné à 2 scans gratuits / jour / utilisateur

Point d'entrée public permettant aux citoyens de tester un lien ou un QR code suspect sans inscription préalable.