polaris-sdk-python

A server-side SDK for a relying party to verify Polaris identity credentials. It answers one narrow question about a credential a holder presented: is it authentic, and is it authoritative right now? It never returns a person's data.

Naming: this project installs the module polaris_verify (the library). The command-line verifier is the separate project polaris-verify (module polaris_verify_cli).

• Authenticity (offline, cacheable): the ML-DSA-65 signature over SHA3-256(token_value), verified with cryptography (and liboqs as a second witness when present), optionally against trusted issuer anchor keys.
• Authorization (online, fresh): the issuer's POST /api/v1/verify, authenticating as a registered organization with OAuth2 client-credentials.

accept requires both; without a reachable issuer the verdict is provisional. Self-contained: only cryptography plus the standard library.

from polaris_verify import PolarisVerifier

v = PolarisVerifier(
    issuer_url="https://issuer.example",
    client_id="rp_...", client_secret="...",         # from `polaris rp-register`
    anchors=["<issuer public key hex>"],             # optional trust anchors
)
verdict = v.verify_presentation(presentation)        # a wallet presentation, or a bare pack
print(verdict.decision)                              # "accept" | "reject" | "provisional"

Offline only (no issuer_url) yields a provisional verdict from authenticity alone. verify_authenticity(pack, anchors) exposes the offline check directly.

A first run needs no issuer and no credential of your own: the repository publishes test vectors.

base=https://raw.githubusercontent.com/EgorKhaklin/polaris-id/main/vectors
curl -sO $base/ml-dsa-65-valid.json && curl -sO $base/ml-dsa-65-tampered-signature.json
python3 -c "
import json
from polaris_verify import verify_authenticity
for f in ('ml-dsa-65-valid.json', 'ml-dsa-65-tampered-signature.json'):
    print(f, verify_authenticity(json.load(open(f)), None).authentic)"

The first prints True, the second False. Walked on 2026-09-23 from a clean virtualenv against the package on PyPI.

What it verifies

Everything below is offline and self-contained. Signatures are accepted under two FIPS 204 parameter sets, ML-DSA-65 (the default) and ML-DSA-87; ML-DSA-44 and any other value are refused (wire spec section 6).

Both SDKs, and the detached verifier, read the values they compare one way (wire spec section 1): a key or a digest is a hex string in any case; an agency or context id is a string or an integer of at most 2^53 - 1; a grant id, a nonce, an action or a token value is a string or such an integer, read as text. Anything else matches nothing, so the same bytes get one answer in every language.

• verify_authenticity(pack, anchors): the authenticity pack.
• verify_status_assertion(assertion, now): the short-lived signed status assertion.
• verify_presentation(presentation, ...): a wallet presentation, or a bare pack.
• verify_signed_artifact(obj, now): every other signed artifact of the wire spec: the epoch checkpoint, revocation feed, federation manifest, status bundle, transparency STH, timestamp, registry, exchange request, exchange receipt, mint statement, signed document, ID token and trust list (authenticity, freshness where windowed, and the artifact's commitment or self-consistency).
• verify_cross_authority(...): the federation trust decision (accept / reject) under the relying party's trust anchors; with none, no manifest is trusted.
• verify_exchange_request(...), verify_exchange_receipt(...), verify_exchange_mint(...): an exchange artifact in use: whether it is by the party expected, whether the requester was attested in its context at a stated instant (and by whom, for a receipt), and whether the bodies held match the commitments.

The SDK passes every case of the conformance suite (281 cases, measured against the repository on 2026-10-01) and every case of the frozen version-1 set under scripts/polaris-compat-suite.py, which runs on every CI push.

Conformance

This SDK is the reference implementation of the Polaris verification conformance suite (../../conformance/). python -m polaris_verify.conformance implements the language-agnostic verifier CLI the suite drives; passing the suite is the integration contract. See conformance/SPEC.md.