🔗 SoWasIt - Documentation Technique

Architecture et modèles de données de la plateforme d'intégrité

Concepts & Garanties Techniques

SoWasIt est une infrastructure d'ancrage cryptographique conçue pour garantir l'intégrité absolue de vos données via des preuves d'existence immuables et mathématiquement vérifiables.

Pourquoi SoWasIt est fiable :

Immuabilité par chaînage : Chaque bloc contient le double hash du précédent (SHA-256). Modifier un seul bit dans l'historique invalide mathématiquement toute la chaîne suivante.
Horodatage certifié : L'heure de création est enregistrée et scellée dans le double hash du bloc.
Indépendance de la preuve : La preuve (hash + contenu) est exportable. Son intégrité peut être vérifiée avec des outils standards, sans dépendre de notre plateforme.

Mécanisme d'Ancrage

L'originalité de SoWasIt réside dans son architecture à double niveau :

[ Votre App ] -> [ Chaîne Privée ] -> [ Chaîne d'Ancrage Publique ]
      |               |                       |
   Données      Ordre & Contexte        Preuve Globale

Chaque événement de votre application est d'abord enregistré dans votre chaîne privée (pour garder vos données confidentielles), puis immédiatement ancré dans la chaîne publique partagée.

Le registre partagé : Tous les clients de SoWasIt s'ancrent dans la même chaîne publique. Cela crée une interdépendance cryptographique : pour falsifier vos données, il faudrait falsifier l'historique de tous les clients de la plateforme simultanément.

Atomicité & Fiabilité

Pour garantir qu'une preuve existe dès qu'une opération est confirmée, SoWasIt utilise des mécanismes de transaction avancés.

Transactions Atomiques

L'écriture dans votre chaîne et l'ancrage public sont exécutés au sein d'une transaction unique et atomique.

Garantie : Si l'ancrage public échoue, l'enregistrement privé est annulé. Vous n'avez jamais de 'preuve partielle'.

Gestion des Verrous

L'utilisation de verrous système garantit un ordre de succession parfait des blocs, évitant toute condition de course, même en cas de fortes sollicitations simultanées.

Sécurité & Isolation

Bien que l'infrastructure soit partagée (Multi-tenant), l'isolation est hermétique.

Isolation logique : Chaque requête est filtrée par un tenant_id au niveau du moteur de base de données. Un utilisateur d'un tenant A ne peut jamais, par construction, adresser une chaîne du tenant B.
Secrets hachés : Les clés API et les tokens de session ne sont jamais stockés en clair. Seul leur hash SHA-256 est conservé.
Idempotence : Le système supporte des clés d'idempotence. Si vous renvoyez la même requête, SoWasIt détecte le doublon et renvoie la preuve originale.

Référence API

L'API est RESTful et communique exclusivement en JSON via HTTPS.

Documentation complète : Une documentation interactive Swagger (OpenAPI) est disponible sur https://api.sowasit.io/api-docs/v1

Authentification

Utilisez le header X-API-Key pour vos appels serveurs.

GET /v1/chains
Host: api.sowasit.io
X-API-Key: your_api_key_here

Gestion des Chaînes

Une chaîne est un conteneur logique pour vos preuves.

Méthode	Endpoint	Description
`GET`	`/v1/chains`	Liste vos chaînes
`POST`	`/v1/chains`	Crée une nouvelle chaîne

Ancrage de Blocs

C'est l'opération principale pour créer une preuve.

POST /v1/chains/{chainId}/blocks
{
  "data": {
    "event": "document_signed",
    "hash": "e3b0c442...",
    "user_id": "user_42"
  }
}

Réponse : Vous recevez immédiatement le hash du bloc et son prev_hash, constituant votre preuve d'existence.

Versionnement de Bloc

Mettez à jour les données existantes tout en conservant un historique immuable. Créez de nouvelles versions de blocs qui se lient aux versions précédentes via les champs prevState/nextState.

Comment ça marche

Lorsque vous mettez à jour un bloc (PUT /chains/{chainId}/blocks/{blockId}), un nouveau bloc est créé avec le contenu mis à jour. Le champ prevState du nouveau bloc pointe vers l'ID de l'ancien bloc, et le nextState de l'ancien bloc est mis à jour pour pointer vers le nouveau. Cela crée une chaîne de versions incassable.

PUT /v1/chains/{chainId}/blocks/{blockId}
{
  "content": {
    "event": "document_updated",
    "version": 2
  }
}

Naviguer dans les versions

Chaque bloc retourné par l'API contient les champs metadata.prevState (ID du bloc précédent) et metadata.nextState (ID du bloc suivant). Un bloc avec nextState à null est la version la plus récente. Pour remonter l'historique, suivez la chaîne prevState de bloc en bloc. Des SDK facilitant cette navigation sont prévus.

Webhooks (Callbacks)

Automatisez vos workflows en recevant des notifications en temps réel lors de l'ajout de nouveaux blocs dans vos chaînes.

Étape 1 — Créer le webhook

Appelez POST /v1/chains/{chainId}/callbacks avec votre URL. L'API vous retourne un secret (à stocker précieusement, il ne sera plus affiché) et un validation_challenge (ex: "tomato").

POST /v1/chains/{chainId}/callbacks
{
  "url": "https://yourapp.com/webhook"
}

// Response
{
  "data": {
    "secret": "a3f8c2d1...",
    "validation_challenge": "tomato"
  }
}

Étape 2 — Préparer votre endpoint

Votre serveur doit répondre aux requêtes GET sur votre URL avec le paramètre ?check=true en retournant exactement : {"challenge": "tomato"} (remplacez par votre challenge réel).

// GET https://yourapp.com/webhook?check=true
{ "challenge": "tomato" }

Étape 3 — Valider le webhook

Appelez POST /v1/chains/{chainId}/callbacks/{id}/validate. SoWasIt contacte votre endpoint, vérifie la réponse, et active le webhook si tout est correct.

Vérifier les notifications reçues

Chaque notification inclut deux headers : X-Callback-Secret (votre secret brut) et X-Callback-Signature (HMAC-SHA256 du body signé avec votre secret). Recalculez le HMAC côté serveur et comparez-le au header pour vous assurer que la notification vient bien de SoWasIt.

// Node.js example
const crypto = require('crypto');
const sig = req.headers['x-callback-signature'];
const expected = crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(req.rawBody)
  .digest('hex');
if (sig !== expected) return res.status(401).send('Invalid signature');

Idempotence : Chaque notification contient une idempotency_key unique. Stockez-la et ignorez toute notification avec une clé déjà traitée — SoWasIt réessaie en cas d'échec (3 tentatives : 30s, 2min, 10min).