SDK guides.

Client and offline verification for the Sovereign Sign-off Protocol, at the same depth in four languages. Sign the upstream lifecycle, open a case for a human to sign, and verify a sealed record with no server. Current release 0.4.0 — every SDK tagged at the same commit.

client: sign events · open a case · record the outcome·verify: offline, per-check, no server trust

Pick a language once — every snippet follows.

01 / install

From the package registry.

You supply a token with read access. Releases are git tags — pin the tag for a reproducible build.

install · python

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

02 / open a case

Sign the upstream events, then open the case.

The response carries the submission_id and the approver_url where a human signs. due_at is required — every case carries an explicit approval SLA. Pass an optional quorum policy for a multi-approver sign-off.

open a case · 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 / learn the outcome

Push with a webhook, or pull with a poll.

Register a webhook at create time — it fires once, when the decision seals, and you author the payload. Or poll the case as a backstop. Records carry the signer's role, never their name.

learn & record the outcome · 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 / verify offline

Verify a sealed record with no server.

The record alone covers the claim hash, the webauthn signatures, quorum satisfaction and the trust wrap; add anchors.json and timestamp.tsr for the rekor and rfc 3161 checks. The trust key comes from you, out-of-band — a bundle can never self-certify. An omitted input yields skip, not pass.

verify offline · 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 / coverage

Every check, every language.

Canonicalization is rfc 8785 jcs, byte-identical across the four SDKs — a record signed via one verifies in any other. The verifier dispatches on the record's signatures, so single-approver, ratify-quorum and independent-vote records are all handled without you picking a shape.

✓canonical claim hash

✓ed25519 trust signature

✓webauthn user signature · cose/cbor

✓quorum slot satisfaction · distinct signers

✓independent resolution · recomputed tally, veto

✓rekor anchor · set, inclusion proof, entry binding

✓rfc 3161 timestamp · imprint, cms signature, tsa chain