zanii-certify

Python SDK and certify CLI for Zanii Certify fingerprints, signed certificates, status, evidence sharing, runtime assurance and scheme governance. Requires Python 3.11 or newer. Public functions are exported by the zanii_certify module; common signed formats are checked against the TypeScript SDK (@zanii/certify on npm) using shared vectors.

Install

pip install zanii-certify
certify verify cert.json --online https://lab.zanii.agency

Certificate, status and signature checks work on every supported Python. The strict text-normalisation policy used to grade test suites pins the Unicode version and currently supports Unicode 16 and 17 (Python 3.14 or newer); on an older Python it reports the policy as unsupported instead of grading with different Unicode tables.

Paths in backticks below (spec/..., conformance/...) are files of the Zanii Certify source repository, which is private; the specification documents are available from Zanii on request (info@zanii.agency).

Use this checkout

From the repository root, install the locked workspace and inspect the current CLI:

uv sync --frozen
uv run certify --help-v2

Save this as example.py at the repository root and run uv run python example.py. It needs no server, network access or signing key:

from zanii_certify import (
    build_fingerprint,
    check_fingerprint,
    prompt_sha256,
    runtime_request_hash,
    sha256_bytes,
)

fingerprint = build_fingerprint(
    model="example-model@1",
    prompt=prompt_sha256("Answer using the approved policy."),
    tools=None,
    policy=None,
    knowledge=None,
)
assert check_fingerprint(fingerprint)
print(fingerprint["id"])

# Commit the exact request body bytes; this hash alone grants no permission.
body = '{"amount_minor":100,"currency":"USD"}'
print(runtime_request_hash({
    "method": "POST",
    "url": "https://bank.example/payments",
    "body_sha256": sha256_bytes(body),
}))

This produces the same two hashes as the TypeScript example (packages/certify/README.md). Fingerprint inputs contain hashes or None, rather than raw prompts/documents. Keep the original bytes: changing whitespace can change a commitment.

Verification policy

verify_certificate(certificate, **options) is synchronous and returns a dictionary with ok and reasons. Optional checks run when their inputs/policies are supplied; an ok result alone does not mean every relying-party requirement was checked.

• Supply fresh signed status and revocation_list, the expected fingerprint, and now when a reproducible verification time is required.
• Supply an independently approved issuer_policy and corresponding issuer_doc. Downloaded metadata cannot nominate trusted keys. Key/PQ changes require local review; allow_no_pq cannot override the pinned policy.
• Supply pq/status_pq when required. For Level 3, supply the audit plus trusted_bodies or an independently rooted body_register. Add witness, licence and release policies where required. Strict withdrawal checking uses the withdrawal log and releases["rejectWithdrawn"] = True; signed JSON policy field names retain their wire spelling, even in Python.

See the full verify_certificate signature (python/src/zanii_certify/certificate.py), policy tests (python/tests/test_verification_policy.py) and certificate contract (spec/certificate.md). Legacy optional behavior remains for compatibility; choose your relying-party policy explicitly. Offline evidence cannot reveal an undisclosed newer checkpoint or revocation.

The CLI is offline by default. --help-v2 lists current strict-policy, audit, witness and release options. --online enables bounded retrieval, including required PQ material. Accept only exit code 0 when every CLI check is required; exit code 2 means not fully checked. See the CLI contract (spec/cli.md). Python issuer retrieval uses at most four daemon-worker slots; a timed-out standard-library request may occupy its slot until it finishes.

Contracts and limits

Format-specific byte/count limits bound builders and verifiers. Preserve trusted freshness watermarks independently when the contract requires them. An inclusion proof establishes commitment, not content truth, ACL permission or quality. Node-only Nitro verification, runtime reporter and reference HTTP gateway are not exported by this Python package.

Check changes

Run from the repository root:

uv run pytest python/tests
uv run pytest python/tests/test_verification_policy.py
uv run ruff check python

Shared vectors (spec/vectors) and conformance tests (conformance) verify the common wire formats and preserve old signed bytes when adding new versions. Local SDK tests do not qualify deployment security or capacity; see the readiness report (docs/readiness-report.md).