zisu-app-sdk 0.1.0__tar.gz

zisu_app_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: zisu-app-sdk
+Version: 0.1.0
+Summary: Python SDK for Zisu OIDC and embedded launch ticket login.
+Author: Zisu
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+
+# zisu-app-sdk
+
+Python SDK for Zisu OIDC login and embedded iframe launch ticket login.
+
+## Core usage
+
+```python
+from zisu_app_sdk import ZisuOIDCClient
+
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = client.get_authorization_url()
+print(auth.url)
+
+result = client.exchange_launch_ticket(
+    launch_ticket="...",
+    expected_nonce="nonce-from-frame",
+)
+print(result.user.sub)
+```
+
+## FastAPI helper
+
+```python
+from fastapi import FastAPI
+from zisu_app_sdk import ZisuFastAPIAuth, ZisuOIDCClient
+
+app = FastAPI()
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = ZisuFastAPIAuth(client, app_session_secret="change-me")
+app.include_router(auth.router())
+```
+
+Set `cookie_secure=True` when the app is served over HTTPS.
+
+Routes added by the helper:
+
+- `GET /login/zisu`
+- `GET /auth/zisu/callback`
+- `POST /auth/zisu/embed`
+- `GET /api/me`

zisu_app_sdk-0.1.0/README.md

@@ -0,0 +1,52 @@
+# zisu-app-sdk
+
+Python SDK for Zisu OIDC login and embedded iframe launch ticket login.
+
+## Core usage
+
+```python
+from zisu_app_sdk import ZisuOIDCClient
+
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = client.get_authorization_url()
+print(auth.url)
+
+result = client.exchange_launch_ticket(
+    launch_ticket="...",
+    expected_nonce="nonce-from-frame",
+)
+print(result.user.sub)
+```
+
+## FastAPI helper
+
+```python
+from fastapi import FastAPI
+from zisu_app_sdk import ZisuFastAPIAuth, ZisuOIDCClient
+
+app = FastAPI()
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = ZisuFastAPIAuth(client, app_session_secret="change-me")
+app.include_router(auth.router())
+```
+
+Set `cookie_secure=True` when the app is served over HTTPS.
+
+Routes added by the helper:
+
+- `GET /login/zisu`
+- `GET /auth/zisu/callback`
+- `POST /auth/zisu/embed`
+- `GET /api/me`

zisu_app_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zisu-app-sdk"
+version = "0.1.0"
+description = "Python SDK for Zisu OIDC and embedded launch ticket login."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Zisu" }
+]
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100", "starlette>=0.27"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

zisu_app_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zisu_app_sdk-0.1.0/src/zisu_app_sdk/__init__.py

@@ -0,0 +1,16 @@
+from .client import ZisuOIDCClient
+from .errors import ZisuAuthError, ZisuHTTPError, ZisuTokenError
+from .fastapi import ZisuFastAPIAuth
+from .models import AuthorizationURL, ZisuLoginResult, ZisuTokenSet, ZisuUser
+
+__all__ = [
+    "AuthorizationURL",
+    "ZisuAuthError",
+    "ZisuFastAPIAuth",
+    "ZisuHTTPError",
+    "ZisuLoginResult",
+    "ZisuOIDCClient",
+    "ZisuTokenError",
+    "ZisuTokenSet",
+    "ZisuUser",
+]

zisu_app_sdk-0.1.0/src/zisu_app_sdk/client.py

@@ -0,0 +1,165 @@
+import secrets
+from typing import Any, Dict, Mapping, Optional
+from urllib import parse
+
+from .http import UrllibHTTPClient
+from .jwt import verify_id_token as verify_jwt_id_token
+from .models import AuthorizationURL, ZisuLoginResult, ZisuTokenSet, ZisuUser
+
+LAUNCH_TICKET_GRANT_TYPE = "urn:zisu:oauth:grant-type:launch_ticket"
+
+
+class ZisuOIDCClient:
+    def __init__(
+        self,
+        issuer: str,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: Optional[str] = None,
+        scope: str = "openid profile email",
+        timeout: float = 10.0,
+        http_client: Optional[Any] = None,
+    ):
+        self.issuer = issuer.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+        self.scope = scope
+        self.http = http_client or UrllibHTTPClient(timeout=timeout)
+        self._discovery: Optional[Dict[str, Any]] = None
+        self._jwks: Optional[Dict[str, Any]] = None
+
+    def discovery(self) -> Dict[str, Any]:
+        if self._discovery is None:
+            self._discovery = self.http.get_json(f"{self.issuer}/.well-known/openid-configuration")
+        return self._discovery
+
+    def jwks(self) -> Dict[str, Any]:
+        if self._jwks is None:
+            self._jwks = self.http.get_json(self.discovery()["jwks_uri"])
+        return self._jwks
+
+    def get_authorization_url(
+        self,
+        state: Optional[str] = None,
+        nonce: Optional[str] = None,
+        scope: Optional[str] = None,
+        redirect_uri: Optional[str] = None,
+        extra_params: Optional[Mapping[str, str]] = None,
+    ) -> AuthorizationURL:
+        state = state or secrets.token_urlsafe(24)
+        nonce = nonce or secrets.token_urlsafe(24)
+        redirect_uri = redirect_uri or self.redirect_uri
+        if not redirect_uri:
+            raise ValueError("redirect_uri is required")
+
+        params = {
+            "response_type": "code",
+            "client_id": self.client_id,
+            "redirect_uri": redirect_uri,
+            "scope": scope or self.scope,
+            "state": state,
+            "nonce": nonce,
+        }
+        if extra_params:
+            params.update(extra_params)
+
+        endpoint = self.discovery()["authorization_endpoint"]
+        return AuthorizationURL(f"{endpoint}?{parse.urlencode(params)}", state, nonce)
+
+    def handle_callback(
+        self,
+        code: str,
+        state: str,
+        expected_state: str,
+        expected_nonce: str,
+        redirect_uri: Optional[str] = None,
+    ) -> ZisuLoginResult:
+        if not expected_state or state != expected_state:
+            from .errors import ZisuTokenError
+
+            raise ZisuTokenError("invalid oauth state")
+
+        token_set = self.exchange_code(code, redirect_uri=redirect_uri)
+        return self._login_result(token_set, expected_nonce=expected_nonce)
+
+    def exchange_code(self, code: str, redirect_uri: Optional[str] = None) -> ZisuTokenSet:
+        redirect_uri = redirect_uri or self.redirect_uri
+        if not redirect_uri:
+            raise ValueError("redirect_uri is required")
+
+        data = self.http.post_form(
+            self.discovery()["token_endpoint"],
+            {
+                "grant_type": "authorization_code",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "code": code,
+                "redirect_uri": redirect_uri,
+            },
+        )
+        return self._token_set(data)
+
+    def exchange_launch_ticket(
+        self,
+        launch_ticket: str,
+        expected_nonce: Optional[str] = None,
+    ) -> ZisuLoginResult:
+        data = self.http.post_form(
+            self.discovery()["token_endpoint"],
+            {
+                "grant_type": LAUNCH_TICKET_GRANT_TYPE,
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+                "launch_ticket": launch_ticket,
+            },
+        )
+        return self._login_result(self._token_set(data), expected_nonce=expected_nonce)
+
+    def verify_id_token(self, id_token: str, expected_nonce: Optional[str] = None) -> Dict[str, Any]:
+        return verify_jwt_id_token(
+            id_token,
+            jwks=self.jwks(),
+            issuer=self.discovery()["issuer"],
+            audience=self.client_id,
+            nonce=expected_nonce,
+        )
+
+    def fetch_userinfo(self, access_token: str) -> Dict[str, Any]:
+        return self.http.get_json(
+            self.discovery()["userinfo_endpoint"],
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+
+    def _login_result(self, token_set: ZisuTokenSet, expected_nonce: Optional[str]) -> ZisuLoginResult:
+        claims = self.verify_id_token(token_set.id_token, expected_nonce=expected_nonce)
+        userinfo = self.fetch_userinfo(token_set.access_token)
+        user = self._user_from_claims(claims, userinfo)
+        return ZisuLoginResult(user=user, tokens=token_set, id_token_claims=claims, userinfo=userinfo)
+
+    def _token_set(self, data: Dict[str, Any]) -> ZisuTokenSet:
+        if not data.get("access_token") or not data.get("id_token"):
+            from .errors import ZisuTokenError
+
+            raise ZisuTokenError("token response missing access_token or id_token")
+        return ZisuTokenSet(
+            access_token=data["access_token"],
+            id_token=data["id_token"],
+            token_type=data.get("token_type", "Bearer"),
+            expires_in=int(data.get("expires_in", 0)),
+            scope=data.get("scope", ""),
+            refresh_token=data.get("refresh_token"),
+            raw=dict(data),
+        )
+
+    def _user_from_claims(self, claims: Dict[str, Any], userinfo: Dict[str, Any]) -> ZisuUser:
+        merged = dict(claims)
+        merged.update({k: v for k, v in userinfo.items() if v not in (None, "")})
+        return ZisuUser(
+            sub=str(merged.get("sub", "")),
+            name=merged.get("name", ""),
+            email=merged.get("email", ""),
+            avatar_url=merged.get("avatar_url", ""),
+            org_id=merged.get("org_id", ""),
+            claims=merged,
+        )

zisu_app_sdk-0.1.0/src/zisu_app_sdk/errors.py

@@ -0,0 +1,14 @@
+class ZisuAuthError(Exception):
+    """Base SDK error."""
+
+
+class ZisuHTTPError(ZisuAuthError):
+    def __init__(self, status_code: int, body: str):
+        super().__init__(f"zisu http error {status_code}: {body}")
+        self.status_code = status_code
+        self.body = body
+
+
+class ZisuTokenError(ZisuAuthError):
+    """Raised when an ID token or app session token is invalid."""
+

zisu_app_sdk-0.1.0/src/zisu_app_sdk/fastapi.py

@@ -0,0 +1,123 @@
+from typing import Any, Dict, Optional
+
+from .jwt import sign_session, verify_session
+
+
+class ZisuFastAPIAuth:
+    def __init__(
+        self,
+        client: Any,
+        app_session_secret: str,
+        success_redirect_path: str = "/",
+        session_cookie_name: str = "zisu_app_session",
+        oauth_state_cookie_name: str = "zisu_oauth_state",
+        oauth_nonce_cookie_name: str = "zisu_oauth_nonce",
+        session_expires_in: int = 60 * 60 * 8,
+        cookie_secure: bool = False,
+    ):
+        if not app_session_secret:
+            raise ValueError("app_session_secret is required")
+        self.client = client
+        self.app_session_secret = app_session_secret
+        self.success_redirect_path = success_redirect_path
+        self.session_cookie_name = session_cookie_name
+        self.oauth_state_cookie_name = oauth_state_cookie_name
+        self.oauth_nonce_cookie_name = oauth_nonce_cookie_name
+        self.session_expires_in = session_expires_in
+        self.cookie_secure = cookie_secure
+
+    def router(self):
+        try:
+            from fastapi import APIRouter, HTTPException, Request, Response
+            from fastapi.responses import JSONResponse, RedirectResponse
+        except ImportError as exc:
+            raise RuntimeError("Install zisu-app-sdk[fastapi] to use FastAPI helpers") from exc
+
+        router = APIRouter()
+
+        @router.get("/login/zisu")
+        def login_zisu():
+            auth = self.client.get_authorization_url()
+            resp = RedirectResponse(auth.url, status_code=302)
+            _set_temp_cookie(resp, self.oauth_state_cookie_name, auth.state, self.cookie_secure)
+            _set_temp_cookie(resp, self.oauth_nonce_cookie_name, auth.nonce, self.cookie_secure)
+            return resp
+
+        @router.get("/auth/zisu/callback")
+        def zisu_callback(request: Request, code: str, state: str):
+            expected_state = request.cookies.get(self.oauth_state_cookie_name, "")
+            expected_nonce = request.cookies.get(self.oauth_nonce_cookie_name, "")
+            result = self.client.handle_callback(code, state, expected_state, expected_nonce)
+            token = self.create_session_token(result.user.claims)
+            resp = RedirectResponse(self.success_redirect_path, status_code=302)
+            _set_session_cookie(resp, self.session_cookie_name, token, self.session_expires_in, self.cookie_secure)
+            resp.delete_cookie(self.oauth_state_cookie_name)
+            resp.delete_cookie(self.oauth_nonce_cookie_name)
+            return resp
+
+        @router.post("/auth/zisu/embed")
+        async def zisu_embed(request: Request, response: Response):
+            body = await request.json()
+            result = self.client.exchange_launch_ticket(
+                launch_ticket=body.get("launch_ticket", ""),
+                expected_nonce=body.get("frame_nonce"),
+            )
+            token = self.create_session_token(result.user.claims)
+            _set_session_cookie(response, self.session_cookie_name, token, self.session_expires_in, self.cookie_secure)
+            return {
+                "session_token": token,
+                "expires_in": self.session_expires_in,
+                "user": _public_user(result.user.claims),
+            }
+
+        @router.get("/api/me")
+        def me(request: Request):
+            user = self.current_user(request)
+            if not user:
+                raise HTTPException(status_code=401, detail="unauthorized")
+            return JSONResponse({"user": _public_user(user)})
+
+        return router
+
+    def create_session_token(self, claims: Dict[str, Any]) -> str:
+        payload = {
+            "sub": claims.get("sub", ""),
+            "name": claims.get("name", ""),
+            "email": claims.get("email", ""),
+            "avatar_url": claims.get("avatar_url", ""),
+            "org_id": claims.get("org_id", ""),
+        }
+        return sign_session(payload, self.app_session_secret, self.session_expires_in)
+
+    def current_user(self, request: Any) -> Optional[Dict[str, Any]]:
+        token = _bearer_token(request.headers.get("authorization", ""))
+        if not token:
+            token = request.cookies.get(self.session_cookie_name, "")
+        if not token:
+            return None
+        return verify_session(token, self.app_session_secret)
+
+
+def _bearer_token(header: str) -> str:
+    prefix = "bearer "
+    if header.lower().startswith(prefix):
+        return header[len(prefix) :].strip()
+    return ""
+
+
+def _set_temp_cookie(response: Any, name: str, value: str, secure: bool) -> None:
+    response.set_cookie(name, value, max_age=600, httponly=True, secure=secure, samesite="lax")
+
+
+def _set_session_cookie(response: Any, name: str, value: str, max_age: int, secure: bool) -> None:
+    response.set_cookie(name, value, max_age=max_age, httponly=True, secure=secure, samesite="lax")
+
+
+def _public_user(claims: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "sub": claims.get("sub", ""),
+        "name": claims.get("name", ""),
+        "email": claims.get("email", ""),
+        "avatar_url": claims.get("avatar_url", ""),
+        "org_id": claims.get("org_id", ""),
+    }

zisu_app_sdk-0.1.0/src/zisu_app_sdk/http.py

@@ -0,0 +1,39 @@
+import json
+from typing import Any, Dict, Mapping, Optional
+from urllib import parse, request
+from urllib.error import HTTPError
+
+from .errors import ZisuHTTPError
+
+
+class UrllibHTTPClient:
+    def __init__(self, timeout: float = 10.0):
+        self.timeout = timeout
+
+    def get_json(self, url: str, headers: Optional[Mapping[str, str]] = None) -> Dict[str, Any]:
+        req = request.Request(url, headers=dict(headers or {}), method="GET")
+        return self._send_json(req)
+
+    def post_form(
+        self,
+        url: str,
+        data: Mapping[str, str],
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        body = parse.urlencode(data).encode("utf-8")
+        merged = {"Content-Type": "application/x-www-form-urlencoded"}
+        merged.update(headers or {})
+        req = request.Request(url, data=body, headers=merged, method="POST")
+        return self._send_json(req)
+
+    def _send_json(self, req: request.Request) -> Dict[str, Any]:
+        try:
+            with request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+        except HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise ZisuHTTPError(exc.code, body) from exc
+
+        if not raw:
+            return {}
+        return json.loads(raw)

zisu_app_sdk-0.1.0/src/zisu_app_sdk/jwt.py

@@ -0,0 +1,160 @@
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Iterable, Optional, Tuple
+
+from .errors import ZisuTokenError
+
+_SHA256_DER_PREFIX = bytes.fromhex("3031300d060960864801650304020105000420")
+
+
+def b64url_decode(value: str) -> bytes:
+    padding = "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode((value + padding).encode("ascii"))
+
+
+def b64url_encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def parse_jwt(token: str) -> Tuple[Dict[str, Any], Dict[str, Any], bytes, bytes]:
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ZisuTokenError("invalid jwt format")
+
+    header_segment, payload_segment, signature_segment = parts
+    try:
+        header = json.loads(b64url_decode(header_segment))
+        claims = json.loads(b64url_decode(payload_segment))
+    except (ValueError, TypeError) as exc:
+        raise ZisuTokenError("invalid jwt json") from exc
+
+    signed = f"{header_segment}.{payload_segment}".encode("ascii")
+    signature = b64url_decode(signature_segment)
+    return header, claims, signed, signature
+
+
+def verify_id_token(
+    token: str,
+    jwks: Dict[str, Any],
+    issuer: str,
+    audience: str,
+    nonce: Optional[str] = None,
+    leeway: int = 60,
+) -> Dict[str, Any]:
+    header, claims, signed, signature = parse_jwt(token)
+
+    if header.get("alg") != "RS256":
+        raise ZisuTokenError("unsupported id_token alg")
+
+    jwk = _select_jwk(jwks.get("keys", []), header.get("kid"))
+    _verify_rs256_signature(signed, signature, jwk)
+    _validate_claims(claims, issuer, audience, nonce, leeway)
+    return claims
+
+
+def sign_session(payload: Dict[str, Any], secret: str, expires_in: int) -> str:
+    now = int(time.time())
+    body = dict(payload)
+    body["iat"] = now
+    body["exp"] = now + expires_in
+
+    header = {"alg": "HS256", "typ": "JWT"}
+    header_segment = b64url_encode(json.dumps(header, separators=(",", ":")).encode("utf-8"))
+    payload_segment = b64url_encode(json.dumps(body, separators=(",", ":")).encode("utf-8"))
+    signed = f"{header_segment}.{payload_segment}".encode("ascii")
+    signature = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).digest()
+    return f"{header_segment}.{payload_segment}.{b64url_encode(signature)}"
+
+
+def verify_session(token: str, secret: str, leeway: int = 30) -> Dict[str, Any]:
+    header, claims, signed, signature = parse_jwt(token)
+    if header.get("alg") != "HS256":
+        raise ZisuTokenError("unsupported app session alg")
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).digest()
+    if not hmac.compare_digest(expected, signature):
+        raise ZisuTokenError("invalid app session signature")
+
+    now = int(time.time())
+    exp = int(claims.get("exp", 0))
+    if exp <= now - leeway:
+        raise ZisuTokenError("app session expired")
+    return claims
+
+
+def _select_jwk(keys: Iterable[Dict[str, Any]], kid: Optional[str]) -> Dict[str, Any]:
+    fallback = None
+    for key in keys:
+        if key.get("kty") != "RSA":
+            continue
+        if fallback is None:
+            fallback = key
+        if kid and key.get("kid") == kid:
+            return key
+    if fallback and not kid:
+        return fallback
+    raise ZisuTokenError("matching jwk not found")
+
+
+def _verify_rs256_signature(signed: bytes, signature: bytes, jwk: Dict[str, Any]) -> None:
+    n = int.from_bytes(b64url_decode(jwk["n"]), "big")
+    e = int.from_bytes(b64url_decode(jwk["e"]), "big")
+    sig_int = int.from_bytes(signature, "big")
+    key_size = (n.bit_length() + 7) // 8
+    encoded = pow(sig_int, e, n).to_bytes(key_size, "big")
+
+    digest = hashlib.sha256(signed).digest()
+    expected_suffix = _SHA256_DER_PREFIX + digest
+    if not encoded.startswith(b"\x00\x01") or b"\x00" not in encoded[2:]:
+        raise ZisuTokenError("invalid id_token signature")
+    padding, suffix = encoded[2:].split(b"\x00", 1)
+    if len(padding) < 8 or any(item != 0xFF for item in padding):
+        raise ZisuTokenError("invalid id_token signature")
+    if not hmac.compare_digest(suffix, expected_suffix):
+        raise ZisuTokenError("invalid id_token signature")
+
+
+def _validate_claims(
+    claims: Dict[str, Any],
+    issuer: str,
+    audience: str,
+    nonce: Optional[str],
+    leeway: int,
+) -> None:
+    now = int(time.time())
+    if claims.get("iss") != issuer:
+        raise ZisuTokenError("invalid id_token issuer")
+
+    aud = claims.get("aud")
+    if isinstance(aud, str):
+        valid_audience = aud == audience
+    elif isinstance(aud, list):
+        valid_audience = audience in aud
+    else:
+        valid_audience = False
+    if not valid_audience:
+        raise ZisuTokenError("invalid id_token audience")
+
+    try:
+        exp = int(claims.get("exp", 0))
+    except (TypeError, ValueError) as exc:
+        raise ZisuTokenError("invalid id_token exp") from exc
+    if exp <= now - leeway:
+        raise ZisuTokenError("id_token expired")
+
+    nbf = claims.get("nbf")
+    if nbf is not None:
+        try:
+            nbf_value = int(nbf)
+        except (TypeError, ValueError) as exc:
+            raise ZisuTokenError("invalid id_token nbf") from exc
+        if nbf_value > now + leeway:
+            raise ZisuTokenError("id_token not active yet")
+
+    if nonce is not None and claims.get("nonce") != nonce:
+        raise ZisuTokenError("invalid id_token nonce")
+
+    if not claims.get("sub"):
+        raise ZisuTokenError("missing id_token subject")

zisu_app_sdk-0.1.0/src/zisu_app_sdk/models.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class AuthorizationURL:
+    url: str
+    state: str
+    nonce: str
+
+
+@dataclass(frozen=True)
+class ZisuTokenSet:
+    access_token: str
+    id_token: str
+    token_type: str = "Bearer"
+    expires_in: int = 0
+    scope: str = ""
+    refresh_token: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ZisuUser:
+    sub: str
+    name: str = ""
+    email: str = ""
+    avatar_url: str = ""
+    org_id: str = ""
+    claims: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ZisuLoginResult:
+    user: ZisuUser
+    tokens: ZisuTokenSet
+    id_token_claims: Dict[str, Any]
+    userinfo: Dict[str, Any] = field(default_factory=dict)
+

zisu_app_sdk-0.1.0/src/zisu_app_sdk.egg-info/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: zisu-app-sdk
+Version: 0.1.0
+Summary: Python SDK for Zisu OIDC and embedded launch ticket login.
+Author: Zisu
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+
+# zisu-app-sdk
+
+Python SDK for Zisu OIDC login and embedded iframe launch ticket login.
+
+## Core usage
+
+```python
+from zisu_app_sdk import ZisuOIDCClient
+
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = client.get_authorization_url()
+print(auth.url)
+
+result = client.exchange_launch_ticket(
+    launch_ticket="...",
+    expected_nonce="nonce-from-frame",
+)
+print(result.user.sub)
+```
+
+## FastAPI helper
+
+```python
+from fastapi import FastAPI
+from zisu_app_sdk import ZisuFastAPIAuth, ZisuOIDCClient
+
+app = FastAPI()
+client = ZisuOIDCClient(
+    issuer="http://127.0.0.1:3005",
+    client_id="essay-helper",
+    client_secret="zisu-dev-secret",
+    redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+)
+
+auth = ZisuFastAPIAuth(client, app_session_secret="change-me")
+app.include_router(auth.router())
+```
+
+Set `cookie_secure=True` when the app is served over HTTPS.
+
+Routes added by the helper:
+
+- `GET /login/zisu`
+- `GET /auth/zisu/callback`
+- `POST /auth/zisu/embed`
+- `GET /api/me`

zisu_app_sdk-0.1.0/src/zisu_app_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/zisu_app_sdk/__init__.py
+src/zisu_app_sdk/client.py
+src/zisu_app_sdk/errors.py
+src/zisu_app_sdk/fastapi.py
+src/zisu_app_sdk/http.py
+src/zisu_app_sdk/jwt.py
+src/zisu_app_sdk/models.py
+src/zisu_app_sdk.egg-info/PKG-INFO
+src/zisu_app_sdk.egg-info/SOURCES.txt
+src/zisu_app_sdk.egg-info/dependency_links.txt
+src/zisu_app_sdk.egg-info/requires.txt
+src/zisu_app_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_jwt.py

zisu_app_sdk-0.1.0/src/zisu_app_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zisu_app_sdk-0.1.0/src/zisu_app_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[fastapi]
+fastapi>=0.100
+starlette>=0.27

zisu_app_sdk-0.1.0/src/zisu_app_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+zisu_app_sdk

zisu_app_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,87 @@
+import time
+import unittest
+from urllib import parse
+
+from test_jwt import jwks, signed_jwt
+from zisu_app_sdk import ZisuOIDCClient
+
+
+class FakeHTTP:
+    def __init__(self):
+        self.forms = []
+        self.discovery = {
+            "issuer": "http://127.0.0.1:3005",
+            "authorization_endpoint": "http://127.0.0.1:3005/oauth/authorize",
+            "token_endpoint": "http://127.0.0.1:3005/oauth/token",
+            "userinfo_endpoint": "http://127.0.0.1:3005/oauth/userinfo",
+            "jwks_uri": "http://127.0.0.1:3005/oauth/jwks",
+        }
+
+    def get_json(self, url, headers=None):
+        if url.endswith("/.well-known/openid-configuration"):
+            return self.discovery
+        if url.endswith("/oauth/jwks"):
+            return jwks()
+        if url.endswith("/oauth/userinfo"):
+            return {"sub": "123", "name": "Ada", "email": "ada@example.com"}
+        raise AssertionError(f"unexpected get {url}")
+
+    def post_form(self, url, data, headers=None):
+        self.forms.append((url, dict(data)))
+        claims = {
+            "iss": "http://127.0.0.1:3005",
+            "aud": "essay-helper",
+            "sub": "123",
+            "exp": int(time.time()) + 600,
+            "nonce": "frame-nonce",
+            "name": "Ada",
+        }
+        return {
+            "access_token": "app-access-token",
+            "id_token": signed_jwt(claims),
+            "token_type": "Bearer",
+            "expires_in": 7200,
+            "scope": "openid profile email",
+        }
+
+
+class ClientTests(unittest.TestCase):
+    def test_authorization_url_contains_required_oidc_params(self):
+        http = FakeHTTP()
+        client = ZisuOIDCClient(
+            issuer="http://127.0.0.1:3005",
+            client_id="essay-helper",
+            client_secret="secret",
+            redirect_uri="http://127.0.0.1:8000/auth/zisu/callback",
+            http_client=http,
+        )
+
+        auth = client.get_authorization_url(state="state-1", nonce="nonce-1")
+        parsed = parse.urlparse(auth.url)
+        query = parse.parse_qs(parsed.query)
+
+        self.assertEqual(parsed.path, "/oauth/authorize")
+        self.assertEqual(query["response_type"], ["code"])
+        self.assertEqual(query["client_id"], ["essay-helper"])
+        self.assertEqual(query["state"], ["state-1"])
+        self.assertEqual(query["nonce"], ["nonce-1"])
+
+    def test_exchange_launch_ticket_uses_custom_grant_and_returns_user(self):
+        http = FakeHTTP()
+        client = ZisuOIDCClient(
+            issuer="http://127.0.0.1:3005",
+            client_id="essay-helper",
+            client_secret="secret",
+            http_client=http,
+        )
+
+        result = client.exchange_launch_ticket("ticket-1", expected_nonce="frame-nonce")
+
+        self.assertEqual(result.user.sub, "123")
+        self.assertEqual(result.user.email, "ada@example.com")
+        self.assertEqual(http.forms[0][1]["grant_type"], "urn:zisu:oauth:grant-type:launch_ticket")
+        self.assertEqual(http.forms[0][1]["launch_ticket"], "ticket-1")
+
+
+if __name__ == "__main__":
+    unittest.main()

zisu_app_sdk-0.1.0/tests/test_jwt.py

@@ -0,0 +1,153 @@
+import hashlib
+import json
+import math
+import random
+import time
+import unittest
+
+from zisu_app_sdk.errors import ZisuTokenError
+from zisu_app_sdk.jwt import b64url_encode, sign_session, verify_id_token, verify_session
+
+RSA_KEY = None
+
+
+def rsa_key():
+    global RSA_KEY
+    if RSA_KEY is not None:
+        return RSA_KEY
+
+    rng = random.Random(20260428)
+    e = 65537
+    while True:
+        p = _prime(rng, 512)
+        q = _prime(rng, 512)
+        if p == q:
+            continue
+        phi = (p - 1) * (q - 1)
+        if math.gcd(e, phi) == 1:
+            break
+    n = p * q
+    d = pow(e, -1, phi)
+    RSA_KEY = {"n": n, "e": e, "d": d}
+    return RSA_KEY
+
+
+def signed_jwt(claims, kid="test-key"):
+    key = rsa_key()
+    header = {"alg": "RS256", "kid": kid, "typ": "JWT"}
+    header_segment = b64url_encode(json.dumps(header, separators=(",", ":")).encode("utf-8"))
+    payload_segment = b64url_encode(json.dumps(claims, separators=(",", ":")).encode("utf-8"))
+    signed = f"{header_segment}.{payload_segment}".encode("ascii")
+
+    digest = hashlib.sha256(signed).digest()
+    suffix = bytes.fromhex("3031300d060960864801650304020105000420") + digest
+    key_size = (key["n"].bit_length() + 7) // 8
+    padded = b"\x00\x01" + (b"\xff" * (key_size - len(suffix) - 3)) + b"\x00" + suffix
+    signature = pow(int.from_bytes(padded, "big"), key["d"], key["n"]).to_bytes(key_size, "big")
+    return f"{header_segment}.{payload_segment}.{b64url_encode(signature)}"
+
+
+def jwks(kid="test-key"):
+    key = rsa_key()
+    return {
+        "keys": [
+            {
+                "kty": "RSA",
+                "kid": kid,
+                "alg": "RS256",
+                "use": "sig",
+                "n": b64url_encode(key["n"].to_bytes((key["n"].bit_length() + 7) // 8, "big")),
+                "e": b64url_encode(key["e"].to_bytes((key["e"].bit_length() + 7) // 8, "big")),
+            }
+        ]
+    }
+
+
+class JWTTests(unittest.TestCase):
+    def test_verify_id_token(self):
+        claims = {
+            "iss": "http://127.0.0.1:3005",
+            "aud": ["essay-helper"],
+            "sub": "123",
+            "iat": int(time.time()),
+            "exp": int(time.time()) + 600,
+            "nonce": "nonce-1",
+        }
+        token = signed_jwt(claims)
+
+        verified = verify_id_token(
+            token,
+            jwks=jwks(),
+            issuer="http://127.0.0.1:3005",
+            audience="essay-helper",
+            nonce="nonce-1",
+        )
+
+        self.assertEqual(verified["sub"], "123")
+
+    def test_verify_id_token_rejects_wrong_nonce(self):
+        claims = {
+            "iss": "http://127.0.0.1:3005",
+            "aud": "essay-helper",
+            "sub": "123",
+            "exp": int(time.time()) + 600,
+            "nonce": "nonce-1",
+        }
+        token = signed_jwt(claims)
+
+        with self.assertRaises(ZisuTokenError):
+            verify_id_token(
+                token,
+                jwks=jwks(),
+                issuer="http://127.0.0.1:3005",
+                audience="essay-helper",
+                nonce="wrong",
+            )
+
+    def test_session_token_roundtrip(self):
+        token = sign_session({"sub": "123"}, "secret", 60)
+        claims = verify_session(token, "secret")
+        self.assertEqual(claims["sub"], "123")
+
+
+def _prime(rng, bits):
+    while True:
+        candidate = rng.getrandbits(bits)
+        candidate |= (1 << (bits - 1)) | 1
+        if _is_probable_prime(candidate):
+            return candidate
+
+
+def _is_probable_prime(n):
+    small_primes = [3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37]
+    if n < 2:
+        return False
+    for p in small_primes:
+        if n == p:
+            return True
+        if n % p == 0:
+            return False
+
+    d = n - 1
+    r = 0
+    while d % 2 == 0:
+        d //= 2
+        r += 1
+
+    for a in [2, 3, 5, 7, 11, 13, 17]:
+        if a >= n:
+            continue
+        x = pow(a, d, n)
+        if x == 1 or x == n - 1:
+            continue
+        for _ in range(r - 1):
+            x = pow(x, 2, n)
+            if x == n - 1:
+                break
+        else:
+            return False
+    return True
+
+
+if __name__ == "__main__":
+    unittest.main()