sdk/python

Asynchrones Python-Server-SDK für netzwerklose JWT-Prüfung,Anfrage-Authentifizierung und Webhook-Signaturvalidierung.

Zustand

Implementiert und lokal verifiziert. Die echteIdP-Round-Trip-Verifizierung (JWKS-Abruf, Token-Signierung/Prüfung gegeneine Live-XID-Instanz) wurde noch nicht durchgeführt und muss vor demProduktionseinsatz abgeschlossen werden.

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Die Anfrageauthentifizierung akzeptiert standardmäßig nur Bearer. Ein anwendungseigenes JWT-Cookie wird nur gelesen, wenn sein exakter Name konfiguriert ist. Das opake Core-Cookie __Host-xid.rt.* wird niemals durchsucht oder lokal verifiziert; tauschen Sie es aus, indem Sie den vollständigen Cookie-Header ohne Weiterleitungen an den exakt gleichursprünglichen Endpunkt POST /v1/sessions/token weiterleiten, und akzeptieren Sie nur eine Antwort, die ausschließlich das Feld token enthält.

Installieren

pip install "xid @ git+https://github.com/StringKe/xid#subdirectory=sdk/python"

Schnellstart

Erstellen Sie beim Start einen XidClient und verwenden Sie ihnwieder. Der Client speichert JWKS intern zwischen.

from xid import XidClient

client = XidClient(
    issuer="https://xid.dev",
    audience="https://api.yourapp.com",  # optional
)

# Verify a token
claims = await client.verify_token("eyJ...")
print(claims.sub, claims.email, claims.scope)

# Authenticate a request (Bearer-only by default)
status = await client.authenticate_request(headers=dict(request.headers))
if not status.authenticated:
    raise Unauthorized()
user_id = status.claims.sub

# Explicit same-origin Core session -> JWT exchange
token = await client.exchange_session_token(
    incoming_request_url="https://app.example.com/account",
    cookie_header=request.headers["cookie"],
)

Webhook prüfen

from xid import WebhookVerificationError

try:
    webhook = client.verify_webhook(
        payload=request.body,
        headers=dict(request.headers),
        secret="whsec_xxx",
    )
    import json
    event = json.loads(webhook.body)
except WebhookVerificationError as exc:
    raise BadRequest(str(exc))

FastAPI-Integration

from fastapi import FastAPI, Depends, HTTPException, Request
from xid import XidClient, TokenClaims

app = FastAPI()
xid = XidClient(issuer="https://xid.dev")

@app.on_event("shutdown")
async def shutdown():
    await xid.aclose()

async def require_auth(request: Request) -> TokenClaims:
    status = await xid.authenticate_request(dict(request.headers))
    if not status.authenticated:
        raise HTTPException(status_code=401)
    return status.claims

@app.get("/me")
async def me(claims: TokenClaims = Depends(require_auth)):
    return {"sub": claims.sub, "email": claims.email}

XidClient-Optionen

Parameter	Standard	Beschreibung
`issuer`	erforderlich	XID-Issuer-URL
`audience`	`None`	Erwarteter aud-Claim; None überspringt die Validierung
`jwks_ttl`	`3600`	JWKS-In-Memory-Cache-TTL in Sekunden
`http_timeout`	`10.0`	JWKS-Abruf-Timeout in Sekunden
`cookie_name`	`disabled`	Name des anwendungseigenen JWT-Cookies; nur bei expliziter Konfiguration aktiviert
`leeway`	`0`	Taktversatztoleranz in Sekunden

Kern-API

Methode	Beschreibung
`await client.verify_token(token)`	JWT-String prüfen; löst bei Fehler `TokenVerificationError` aus.
`await client.authenticate_request(headers, cookies)`	Token aus Headern/Cookies extrahieren und prüfen. Gibt `AuthStatus`zurück; löst keine Exception aus.
`client.verify_webhook(payload, headers, secret)`	Synchron. Validiert svix-HMAC-SHA256 + 5-Minuten-Replay-Fenster. Löst beiFehler `WebhookVerificationError` aus.
`await client.aclose()`	Zugrunde liegende HTTP-Client-Ressourcen freigeben.

Plattformhinweise

Async-first. Synchrone Aufrufer (Django/Flask) können mitasyncio.run() wrappen.
Setzt pyjwt[crypto] >=2.8 und httpx >=0.27 voraus. Python3.10+ erforderlich.
Multi-Worker-Deployments teilen keinen JWKS-Cache über Prozesse hinweg.Ein gemeinsamer Cache (Redis) ist eine geplante Verbesserung.