sdk/python

非同期 Python サーバー SDK。ネットワークレス JWT 検証、リクエスト認証、webhook 署名検証をサポートします。

状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 XID インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な __Host-xid.rt.* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

インストール

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

クイックスタート

起動時に XidClient を 1 つ作成して再利用します。クライアントは内部で JWKS をキャッシュします。

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 を検証

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 統合

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 オプション

パラメーター	デフォルト	説明
`issuer`	必須	XID 発行者 URL
`audience`	`None`	expected aud クレーム。None は検証をスキップします
`jwks_ttl`	`3600`	JWKS メモリ内キャッシュ TTL（秒）
`http_timeout`	`10.0`	JWKS 取得タイムアウト（秒）
`cookie_name`	`disabled`	アプリケーション所有の JWT cookie 名。明示的に設定した場合のみ有効
`leeway`	`0`	クロックスキュー許容値（秒）

コア API

方式	説明
`await client.verify_token(token)`	JWT 文字列を検証します。失敗時は `TokenVerificationError` を発生させます。
`await client.authenticate_request(headers, cookies)`	ヘッダー/Cookie からトークンを取得して検証します。`AuthStatus` を返し、例外を発生させません。
`client.verify_webhook(payload, headers, secret)`	同期実行。svix HMAC-SHA256 と 5 分間のリプレイウィンドウを検証します。失敗時は `WebhookVerificationError` を発生させます。
`await client.aclose()`	基礎となる HTTP クライアントリソースを解放します。

プラットフォームの注意事項

非同期ファースト。同期呼び出し元（Django/Flask）は asyncio.run() でラップできます。
pyjwt[crypto] >=2.8 と httpx >=0.27 が必要です。Python 3.10+ が必要です。
マルチワーカーデプロイではプロセス間で JWKS キャッシュを共有しません。共有キャッシュ（Redis）は計画中の改善です。