🔗 SoWasIt - Technische Dokumentation

Architektur und Datenmodelle der Integritätsplattform

Technische Konzepte & Garantien

SoWasIt ist eine kryptografische Verankerungsinfrastruktur, die entwickelt wurde, um die absolute Integrität Ihrer Daten durch unveränderliche und mathematisch überprüfbare Existenzbeweise zu garantieren.

Warum SoWasIt zuverlässig ist:

Gekettete Unveränderlichkeit : Jeder Block enthält den doppelten Hash des vorherigen (SHA-256). Das Ändern eines einzelnen Bits in der Historie macht mathematisch alle nachfolgenden Blöcke ungültig.
Zertifizierter Zeitstempel : Die Erstellungszeit wird aufgezeichnet und im doppelten Hash des Blocks versiegelt.
Unabhängigkeit des Beweises : Der Beweis (Hash + Inhalt) ist exportierbar. Seine Integrität kann mit Standardwerkzeugen überprüft werden, ohne von unserer Plattform abhängig zu sein.

Verankerungsmechanismus

Die Einzigartigkeit von SoWasIt liegt in seiner zweischichtigen Architektur:

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

Jedes Ereignis aus Ihrer Anwendung wird zuerst in Ihrer privaten Kette aufgezeichnet (um Ihre Daten vertraulich zu behandeln) und dann sofort in der gemeinsam genutzten öffentlichen Kette verankert.

Gemeinsames Register : Alle SoWasIt-Clients verankern sich in derselben öffentlichen Kette. Dies schafft eine kryptografische Interdependenz: Um Ihre Daten zu fälschen, müsste man gleichzeitig die Historie aller Clients der Plattform fälschen.

Atomarität & Zuverlässigkeit

Um sicherzustellen, dass ein Beweis existiert, sobald eine Operation bestätigt wird, verwendet SoWasIt fortschrittliche Transaktionsmechanismen.

Atomare Transaktionen

Das Schreiben in Ihre Kette und die öffentliche Verankerung erfolgen in einer einzigen, atomaren Transaktion.

Garantie : Wenn die öffentliche Verankerung fehlschlägt, wird der private Datensatz rückgängig gemacht. Sie haben niemals einen 'Teilbeweis'.

Sperrverwaltung

Die Verwendung von Sperren auf Systemebene gewährleistet eine perfekte Abfolge der Blöcke und verhindert Race Conditions auch bei hoher Gleichzeitigkeit.

Sicherheit & Isolation

Obwohl die Infrastruktur gemeinsam genutzt wird (Multi-Tenant), ist die Isolation hermetisch.

Logische Isolation : Jede Anfrage wird durch eine tenant_id auf Ebene der Datenbank-Engine gefiltert. Ein Benutzer von Tenant A kann konstruktionsbedingt niemals eine Kette von Tenant B ansprechen.
Gehashte Geheimnisse : API-Schlüssel und Sitzungstoken werden niemals im Klartext gespeichert. Nur ihr SHA-256-Hash wird aufbewahrt.
Idempotenz : Das System unterstützt Idempotenz-Schlüssel. Wenn Sie dieselbe Anfrage erneut senden, erkennt SoWasIt das Duplikat und gibt den ursprünglichen Beweis zurück.

API-Referenz

Die API ist RESTful und kommuniziert ausschließlich in JSON über HTTPS.

Vollständige Dokumentation : Eine interaktive Swagger-Dokumentation (OpenAPI) ist verfügbar unter https://api.sowasit.io/api-docs/v1

Authentifizierung

Verwenden Sie den X-API-Key-Header für Ihre Serveraufrufe.

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

Kettenverwaltung

Eine Kette ist ein logischer Container für Ihre Beweise.

Methode	Endpunkt	Beschreibung
`GET`	`/v1/chains`	Listen Sie Ihre Ketten auf
`POST`	`/v1/chains`	Erstellen Sie eine neue Kette

Block-Verankerung

Dies ist die primäre Operation zum Erstellen eines Beweises.

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

Antwort : Sie erhalten sofort den Hash des Blocks und seinen prev_hash, was Ihren Existenzbeweis darstellt.

JSONPath-Suche

Filtern und rufen Sie Ihre Blöcke effizient mit JSONPath-Ausdrücken ab. Ideal für die Verwaltung großer Ketten oder das Ignorieren fehlerhafter Blöcke.

POST /v1/chains/{chainId}/blocks/search
{
  "path": "$.content.type == \"invoice\" && $.content.amount > 100"
}

Beispiele für Ausdrücke

$.content.user == "Alice" : Filtrer par valeur
$.content.status != "draft" : Exclusion
$.content.tags[*] == "urgent" : Recherche dans un tableau

Documentation utile :

Block-Versionierung

Aktualisieren Sie vorhandene Daten unter Beibehaltung einer unveränderlichen Historie. Erstellen Sie neue Versionen von Blöcken, die über die Felder prevState/nextState mit vorherigen Versionen verknüpft sind.

Wie es funktioniert

Wenn Sie einen Block aktualisieren (PUT /chains/{chainId}/blocks/{blockId}), wird ein neuer Block mit dem aktualisierten Inhalt erstellt. Das Feld prevState des neuen Blocks zeigt auf die ID des alten Blocks, und das nextState des alten Blocks wird aktualisiert, um auf den neuen Block zu zeigen. Dies schafft eine unzerbrechliche Versionskette.

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

Versionen navigieren

Jeder von der API zurückgegebene Block enthält metadata.prevState (ID des vorherigen Blocks) und metadata.nextState (ID des nächsten Blocks). Ein Block mit nextState gleich null ist die aktuellste Version. Um die Historie zu durchlaufen, folgen Sie der prevState-Kette von Block zu Block. SDKs zur Vereinfachung dieser Navigation sind geplant.

Webhooks (Callbacks)

Automatisieren Sie Ihre Workflows, indem Sie Echtzeit-Benachrichtigungen erhalten, wenn neue Blöcke zu Ihren Ketten hinzugefügt werden.

Schritt 1 — Webhook erstellen

Rufen Sie POST /v1/chains/{chainId}/callbacks mit Ihrer URL auf. Die API gibt ein secret zurück (sicher aufbewahren — es wird nie wieder angezeigt) und einen validation_challenge (z.B. "tomato").

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

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

Schritt 2 — Ihren Endpunkt vorbereiten

Ihr Server muss auf GET-Anfragen an Ihre URL mit dem Parameter ?check=true antworten und genau zurückgeben: {"challenge": "tomato"} (durch Ihre tatsächliche Challenge ersetzen).

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

Schritt 3 — Webhook validieren

Rufen Sie POST /v1/chains/{chainId}/callbacks/{id}/validate auf. SoWasIt kontaktiert Ihren Endpunkt, prüft die Antwort und aktiviert den Webhook wenn alles korrekt ist.

Eingehende Benachrichtigungen überprüfen

Jede Benachrichtigung enthält zwei Header: X-Callback-Secret (Ihr rohes Secret) und X-Callback-Signature (HMAC-SHA256 des Body, signiert mit Ihrem Secret). Berechnen Sie den HMAC serverseitig neu und vergleichen Sie ihn mit dem Header, um sicherzustellen, dass die Benachrichtigung wirklich von SoWasIt stammt.

// 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');

Idempotenz : Jede Benachrichtigung enthält einen eindeutigen idempotency_key. Speichern Sie ihn und ignorieren Sie Benachrichtigungen mit bereits verarbeiteten Schlüsseln — SoWasIt wiederholt bei Fehler (3 Versuche: 30s, 2min, 10min).

Logs & Debugging

SoWasIt verfolgt technische Operationen, um Ihnen bei der Diagnose Ihrer Integrationen zu helfen.

Debug-Modus

Standardmäßig werden nur wichtige Ereignisse (INFO) und Fehler (ERROR) aufbewahrt. Für eine tiefergehende Analyse können Sie den 'Debug-Modus' vorübergehend über Ihr Dashboard aktivieren. Dies zeichnet alle technischen Details für die gewählte Dauer auf (bis zu 48h).

Aufbewahrung : Protokolle werden 30 Tage lang aufbewahrt, bevor sie automatisch gelöscht werden. Sie können auch eine manuelle Löschung über die Benutzeroberfläche auslösen.