zanii-id

Python SDK for Zanii ID — OAuth 2.1 / OpenID Connect sign-in for products in the Zanii ecosystem.

Authorization Code flow with mandatory PKCE, offline ID-token verification against the issuer's JWKS, and a FastAPI integration that mounts the whole login round-trip for you.

pip install zanii-id

Use it

Configuration comes from ZANII_ISSUER, ZANII_CLIENT_ID, ZANII_CLIENT_SECRET and ZANII_REDIRECT_URI, and is validated eagerly so a misconfigured deployment fails at startup rather than on a user's first login.

from zanii_id import ZaniiClient

zanii = ZaniiClient()
req = zanii.get_authorization_url()       # keep req.state / req.nonce / req.verifier in session
# ... redirect the user to req.url, then on your callback route:
tokens = await zanii.exchange_code(code, req, received_state)
claims = zanii.verify_id_token(tokens.id_token, nonce=req.nonce)
user = await zanii.get_user(tokens.access_token)

FastAPI

from zanii_id import ZaniiClient
from zanii_id.integrations.fastapi import build_auth_router, install_zanii, require_zanii_auth

zanii = ZaniiClient()
install_zanii(app, zanii, session_secret=SECRET)
app.include_router(build_auth_router(zanii, session_secret=SECRET))

@app.get("/dashboard")
async def dashboard(user = Depends(require_zanii_auth)):
    return {"zanii_user_id": user.zanii_user_id}

That mounts /auth/login, /auth/callback and /auth/logout. require_zanii_auth refreshes a stale access token once and rotates the session cookie before giving up.

Provisioning users locally

sub is an immutable zanii_user_id. Upsert on it — never on email, which users change:

INSERT INTO users (zanii_user_id, ...) VALUES ($1, ...)
ON CONFLICT (zanii_user_id) DO NOTHING;

Agent activity

If your product records agent receipts on the Zanii ledger, stamp them with the user's subject tag so they can audit their own slice:

from zanii_id.activity import subject_tag, fetch_activity   # pip install 'zanii-id[subject]'

tag = subject_tag(user.did, client_id)     # pass to record(..., subject_tag=tag)
entries = await fetch_activity(tag)        # every receipt verified offline

Invalid receipts come back with verified=False and a flag_reason rather than being dropped — a truncated slice appends its own flagged entry, so a cut page never reads as complete.

Notes

• alg is pinned from the discovery document, never trusted from the token header.
• Token POSTs are never retried; grants are single-use.
• The JWKS cache refetches exactly once on an unseen kid, then fails hard.

Licence

Apache-2.0. See LICENSE.