SDK-Leitfäden.

Client und Offline-Prüfung für das Sovereign Sign-off Protocol — in vier Sprachen, in derselben Tiefe. Sie signieren die vorgelagerten Ereignisse, eröffnen einen Fall zur persönlichen Freigabe und prüfen versiegelte Aufzeichnungen ganz ohne Server. Aktuelle Version 0.4.0 — alle SDKs auf demselben Commit getaggt.

client: ereignisse signieren · fall eröffnen · ergebnis erfassen·verify: offline, je prüfung, ohne serververtrauen

Einmal die Sprache wählen — alle Snippets ziehen nach.

01 / installation

Aus der Paket-Registry.

Sie hinterlegen ein Token mit Leserecht. Releases sind Git-Tags — für reproduzierbare Builds fixieren Sie den Tag.

installation · python

pip install sovereign-saa-sdk \
  --index-url "https://__token__:<read-token>@registry.example/pypi/simple"

02 / fall eröffnen

Erst die Ereignisse signieren, dann den Fall eröffnen.

Die Antwort enthält die submission_id und die approver_url, unter der eine Person signiert. due_at ist Pflicht — jeder Fall trägt eine verbindliche Freigabefrist. Für Freigaben durch mehrere Personen geben Sie optional eine Quorum-Regel mit.

fall eröffnen · python

from sovereign.saa import Client, Signer, base_claim

signer = Signer.load("saa-client.key")   # generates + persists on first use
client = Client(API_URL, api_key=KEY, signer=signer, tenant="acme-bank")

events = [signer.sign_event({**base_claim("ai.inference.completed", "acme-bank", "subj-001"),
          "result": {"recommendation": "approve", "risk_score": 0.18}})]

resp = client.create_case(
    domain="finance", artifact=b"Pay vendor ACME 12,750 USD",
    filename="wire.txt", mime_type="text/plain",
    client_events=events, subject="subj-001",
    due_at="2026-12-31T17:00:00Z",   # required: approval SLA
    quorum={"dsl": "Senior Credit Officer*2, Compliance",
            "mode": "parallelRoles", "workflow": {"type": "ratify"}})
print(resp["submission_id"], resp["approver_url"])

03 / ergebnis abrufen

Push per Webhook, Pull per Abfrage.

Registrieren Sie den Webhook bereits beim Erstellen: Er wird genau einmal ausgelöst, sobald die Entscheidung versiegelt ist — die Payload definieren Sie selbst. Zur Absicherung lässt sich der Fall zusätzlich abfragen. Aufzeichnungen nennen die Rolle der signierenden Person, nie ihren Namen.

ergebnis abrufen & erfassen · python

# push - webhook registered at create time; fires once, when sealed
resp = client.create_case(..., callback={
    "url": "https://erp.example/hooks/sovereign-sealed",
    "token": "one-time-secret"})    # echoed back for authentication

# pull - poll the case, or as a backstop for a missed webhook
s = client.case_status(resp["submission_id"])
s["status"]                          # "pending" | "sealed"
s["outcome"], s["ledger_uuid"]       # once sealed

# then close the loop: record what the client system actually did
client.record_outcome(ledger_uuid, status="executed")

04 / offline prüfen

Versiegelte Aufzeichnungen ohne Server prüfen.

Die Aufzeichnung allein deckt den Claim-Hashwert, die webauthn-Signaturen, die Quorum-Erfüllung und die Vertrauenssignatur ab; mit anchors.json und timestamp.tsr kommen die rekor- und rfc-3161-Prüfungen hinzu. Den Vertrauensschlüssel liefern Sie selbst, auf separatem Weg — ein Beweispaket kann sich nie selbst beglaubigen. Fehlt eine Eingabe, lautet das Ergebnis skip, nicht pass.

offline prüfen · python

import json
from sovereign.saa import verify_record

record = json.load(open("record.ssp.json"))
trust = open("trust-public.pem").read()          # out-of-band

result = verify_record(
    record, trust, rp_id="app.sovereign.example",
    record_bytes=open("record.ssp.json", "rb").read(),
    anchors=json.load(open("anchors.json")),      # optional: rekor
    tsa_token=open("timestamp.tsr", "rb").read()) # optional: rfc 3161
print(result)          # per-check PASS / FAIL / SKIP + overall
assert result.ok

05 / abdeckung

Jede Prüfung, in jeder Sprache.

Die Kanonisierung folgt rfc 8785 jcs und ist über alle vier SDKs byte-identisch — eine mit einem SDK signierte Aufzeichnung lässt sich mit jedem anderen prüfen. Der Verifizierer richtet sich nach den Signaturen der Aufzeichnung: Einzelfreigabe, Ratifizierungs-Quorum und unabhängige Abstimmung werden erkannt, ohne dass Sie ein Format wählen müssen.

✓kanonischer claim-hashwert

✓ed25519-vertrauenssignatur

✓webauthn-nutzersignatur · cose/cbor

✓quorum-erfüllung je slot · unterschiedliche signierende

✓auflösung der unabhängigen abstimmung · neu berechnete auszählung, veto

✓rekor-anker · set, inklusionsbeweis, eintragsbindung

✓rfc-3161-zeitstempel · imprint, cms-signatur, tsa-kette