Guides SDK.

Le client et la vérification hors ligne du Sovereign Sign-off Protocol, avec la même profondeur dans quatre langages. Signez le cycle de vie amont, ouvrez un dossier pour qu'un humain le signe, vérifiez un enregistrement scellé sans aucun serveur. Version courante 0.4.0 — chaque SDK est taggé sur le même commit.

client : signer les événements · ouvrir un dossier · consigner l'issue·vérifier : hors ligne, contrôle par contrôle, sans confiance envers un serveur

Choisissez votre langage une fois pour toutes — tous les extraits suivent.

01 / installation

Depuis le registre de paquets.

Vous fournissez un jeton doté d'un accès en lecture. Les versions sont des tags git — épinglez le tag pour un build reproductible.

installation · python

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

02 / ouvrir un dossier

Signez les événements amont, puis ouvrez le dossier.

La réponse contient le submission_id et l'approver_url où un humain appose sa signature. Le champ due_at est obligatoire — chaque dossier porte un SLA d'approbation explicite. Ajoutez au besoin une politique de quorum pour une signature à plusieurs approbateurs.

ouvrir un dossier · 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 / connaître l'issue

Webhook en push, ou interrogation en pull.

Enregistrez un webhook à la création du dossier — il se déclenche une seule fois, au scellement de la décision, et vous en définissez le contenu. Ou interrogez le dossier, en guise de filet de sécurité. Les enregistrements portent le rôle du signataire, jamais son nom.

connaître & consigner l'issue · 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 / vérification hors ligne

Vérifier l'enregistrement scellé sans serveur.

L'enregistrement couvre à lui seul l'empreinte de la déclaration, les signatures webauthn, la satisfaction du quorum et l'enveloppe de confiance ; ajoutez anchors.json et timestamp.tsr pour les contrôles rekor et rfc 3161. La clé de confiance vient de vous, par un canal distinct — jamais une archive ne se certifie elle-même. Une entrée omise donne skip, pas pass.

vérification hors ligne · 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 / couverture

Chaque contrôle, chaque langage.

La canonicalisation suit rfc 8785 jcs, identique à l'octet près dans les quatre SDK — un enregistrement signé avec l'un se vérifie avec n'importe quel autre. Le vérificateur s'adapte aux signatures de l'enregistrement : approbateur unique, quorum de ratification ou vote indépendant sont traités sans que vous ayez à choisir un format.

✓empreinte canonique de la déclaration

✓signature de confiance ed25519

✓signature utilisateur webauthn · cose/cbor

✓satisfaction du quorum · signataires distincts

✓résolution indépendante · décompte recalculé, veto

✓ancrage rekor · set, preuve d'inclusion, liaison d'entrée

✓horodatage rfc 3161 · empreinte, signature cms, chaîne tsa