mythos-sdk 0.1.0__tar.gz

mythos_sdk-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+.npm
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Env
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Coverage
+coverage/
+.coverage
+htmlcov/

mythos_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: mythos-sdk
+Version: 0.1.0
+Summary: Official Mythos SDK for Python — launch token verification, usage reporting, and handshake
+Project-URL: Homepage, https://github.com/Mythoswork/mythos-sdk
+Project-URL: Repository, https://github.com/Mythoswork/mythos-sdk
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-jose[cryptography]<4,>=3.3.0
+Provides-Extra: dev
+Requires-Dist: cryptography>=42.0; extra == 'dev'
+Requires-Dist: fastapi[standard]>=0.100.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# mythos-sdk
+
+Official Mythos SDK for Python — launch token verification, usage reporting, and handshake.
+
+## Install
+
+```bash
+pip install mythos-sdk[fastapi]
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Depends
+from mythos_sdk import require_launch_token, report_usage, create_handshake_router
+
+app = FastAPI()
+
+# Handshake endpoint — Mythos pings this before publishing your listing
+app.include_router(create_handshake_router())
+
+# Protected route — verifies and consumes the launch token automatically
+@app.get("/dashboard")
+async def dashboard(session = Depends(require_launch_token())):
+    # session = MythosSession(user_id, email, display_name, listing_id, session_jti)
+    await report_usage(session.session_jti, credits=1, reason="page-view")
+    return {"ok": True}
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MYTHOS_LISTING_ID` | Yes* | — | Your listing ID |
+| `MYTHOS_LISTING_IDS` | Yes* | — | Comma-separated listing IDs (overrides above) |
+| `MYTHOS_API_URL` | No | `https://api.mythos.work` | API base URL override |
+
+*One of `MYTHOS_LISTING_ID` or `MYTHOS_LISTING_IDS` is required.
+
+## API
+
+### `require_launch_token()`
+
+FastAPI dependency. Verifies the RS256 launch token from `?lt=`, enforces single-use semantics, and returns a `MythosSession`. Returns `401` if the token is missing, invalid, or already consumed.
+
+### `report_usage(session_jti, *, credits, reason=None)`
+
+Reports credit consumption against a session. Call after delivering value to the user.
+
+### `create_handshake_router()`
+
+Returns a FastAPI `APIRouter` that mounts `GET /.well-known/mythos-handshake`. Mythos calls this endpoint during listing publish to confirm the SDK is installed and reachable.
+
+### `verify_launch_token(token)`
+
+Low-level token verifier. Returns the decoded payload. Use `require_launch_token()` dependency instead for most cases.
+
+## Security
+
+- Tokens verified via RS256 against the Mythos JWKS endpoint
+- `alg: none` rejected as a hard block
+- Single-use enforcement is non-skippable (ADR-0003)
+- JWKS keys cached 10 minutes with automatic re-fetch on key rotation
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE).

mythos_sdk-0.1.0/README.md

@@ -0,0 +1,67 @@
+# mythos-sdk
+
+Official Mythos SDK for Python — launch token verification, usage reporting, and handshake.
+
+## Install
+
+```bash
+pip install mythos-sdk[fastapi]
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Depends
+from mythos_sdk import require_launch_token, report_usage, create_handshake_router
+
+app = FastAPI()
+
+# Handshake endpoint — Mythos pings this before publishing your listing
+app.include_router(create_handshake_router())
+
+# Protected route — verifies and consumes the launch token automatically
+@app.get("/dashboard")
+async def dashboard(session = Depends(require_launch_token())):
+    # session = MythosSession(user_id, email, display_name, listing_id, session_jti)
+    await report_usage(session.session_jti, credits=1, reason="page-view")
+    return {"ok": True}
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MYTHOS_LISTING_ID` | Yes* | — | Your listing ID |
+| `MYTHOS_LISTING_IDS` | Yes* | — | Comma-separated listing IDs (overrides above) |
+| `MYTHOS_API_URL` | No | `https://api.mythos.work` | API base URL override |
+
+*One of `MYTHOS_LISTING_ID` or `MYTHOS_LISTING_IDS` is required.
+
+## API
+
+### `require_launch_token()`
+
+FastAPI dependency. Verifies the RS256 launch token from `?lt=`, enforces single-use semantics, and returns a `MythosSession`. Returns `401` if the token is missing, invalid, or already consumed.
+
+### `report_usage(session_jti, *, credits, reason=None)`
+
+Reports credit consumption against a session. Call after delivering value to the user.
+
+### `create_handshake_router()`
+
+Returns a FastAPI `APIRouter` that mounts `GET /.well-known/mythos-handshake`. Mythos calls this endpoint during listing publish to confirm the SDK is installed and reachable.
+
+### `verify_launch_token(token)`
+
+Low-level token verifier. Returns the decoded payload. Use `require_launch_token()` dependency instead for most cases.
+
+## Security
+
+- Tokens verified via RS256 against the Mythos JWKS endpoint
+- `alg: none` rejected as a hard block
+- Single-use enforcement is non-skippable (ADR-0003)
+- JWKS keys cached 10 minutes with automatic re-fetch on key rotation
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE).

mythos_sdk-0.1.0/mythos_sdk/__init__.py

@@ -0,0 +1,18 @@
+from .errors import InsufficientFundsError, MythosError, SessionNotFoundError
+from .handshake import create_handshake_router, handshake_router
+from .middleware import require_launch_token
+from .report_usage import report_usage
+from .types import MythosSession
+from .verify import verify_launch_token
+
+__all__ = [
+    "verify_launch_token",
+    "require_launch_token",
+    "report_usage",
+    "handshake_router",
+    "create_handshake_router",
+    "MythosSession",
+    "MythosError",
+    "InsufficientFundsError",
+    "SessionNotFoundError",
+]

mythos_sdk-0.1.0/mythos_sdk/api_client.py

@@ -0,0 +1,37 @@
+import uuid
+from typing import Any
+
+import httpx
+
+from .config import load_config
+from .errors import InsufficientFundsError, SessionNotFoundError
+
+
+async def consume_session(jti: str) -> httpx.Response:
+    config = load_config()
+    async with httpx.AsyncClient() as client:
+        return await client.post(
+            f"{config.api_url}/api/apps/sessions/{jti}/consume",
+            json={},
+        )
+
+
+async def meter_session(jti: str, credits: int, reason: str | None = None) -> None:
+    config = load_config()
+    # charge_id is a per-call idempotency key required by the backend's SQS metering
+    # job dedup (see backend docs/migrations) — generated here, not caller-supplied.
+    body: dict[str, Any] = {"credits": credits, "charge_id": str(uuid.uuid4())}
+    if reason is not None:
+        body["reason"] = reason
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{config.api_url}/api/apps/sessions/{jti}/meter",
+            json=body,
+        )
+
+    if resp.status_code == 402:
+        raise InsufficientFundsError()
+    if resp.status_code == 404:
+        raise SessionNotFoundError(jti)
+    resp.raise_for_status()

mythos_sdk-0.1.0/mythos_sdk/config.py

@@ -0,0 +1,28 @@
+import os
+from dataclasses import dataclass
+
+DEFAULT_API_URL = "https://api.mythos.work"
+
+
+@dataclass
+class MythosConfig:
+    listing_ids: list[str]
+    api_url: str
+
+
+def load_config() -> MythosConfig:
+    api_url = os.environ.get("MYTHOS_API_URL", DEFAULT_API_URL)
+    multi = os.environ.get("MYTHOS_LISTING_IDS")
+    single = os.environ.get("MYTHOS_LISTING_ID")
+
+    if multi:
+        listing_ids = [lid.strip() for lid in multi.split(",") if lid.strip()]
+    elif single:
+        listing_ids = [single]
+    else:
+        listing_ids = []
+
+    if not listing_ids:
+        raise RuntimeError("MYTHOS_LISTING_ID or MYTHOS_LISTING_IDS env var is required")
+
+    return MythosConfig(listing_ids=listing_ids, api_url=api_url)

mythos_sdk-0.1.0/mythos_sdk/errors.py

@@ -0,0 +1,14 @@
+class MythosError(Exception):
+    def __init__(self, message: str, code: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class InsufficientFundsError(MythosError):
+    def __init__(self) -> None:
+        super().__init__("Insufficient funds in wallet", "INSUFFICIENT_FUNDS")
+
+
+class SessionNotFoundError(MythosError):
+    def __init__(self, jti: str) -> None:
+        super().__init__(f"Session not found: {jti}", "SESSION_NOT_FOUND")

mythos_sdk-0.1.0/mythos_sdk/handshake.py

@@ -0,0 +1,54 @@
+import logging
+import os
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+from jose import jwt
+from jose.exceptions import ExpiredSignatureError, JOSEError, JWTError
+
+from .jwks_cache import get_jwks, get_jwks_with_kid_fallback
+
+_logger = logging.getLogger(__name__)
+
+SDK_VERSION = "0.1.0"
+_DEFAULT_API_URL = "https://api.mythos.work"
+# Tokens in this SDK carry no aud/iss claims.
+_DECODE_OPTIONS = {"verify_aud": False, "verify_iss": False}
+
+
+async def _validate_handshake_token(token: str) -> None:
+    api_url = os.environ.get("MYTHOS_API_URL", _DEFAULT_API_URL)
+    jwks = await get_jwks(api_url)
+    try:
+        payload = jwt.decode(token, jwks, algorithms=["RS256"], options=_DECODE_OPTIONS)
+    except ExpiredSignatureError:
+        raise
+    except JWTError:
+        jwks = await get_jwks_with_kid_fallback(api_url)
+        payload = jwt.decode(token, jwks, algorithms=["RS256"], options=_DECODE_OPTIONS)
+
+    if payload.get("purpose") != "handshake-check":
+        raise JWTError("Token purpose is not handshake-check")
+
+
+def create_handshake_router() -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/.well-known/mythos-handshake")
+    async def mythos_handshake(request: Request) -> JSONResponse:
+        token = request.query_params.get("lt")
+        if not token:
+            return JSONResponse({"error": "Missing launch token"}, status_code=401)
+        try:
+            await _validate_handshake_token(token)
+        except JOSEError:
+            return JSONResponse({"error": "Invalid launch token"}, status_code=401)
+        except Exception:
+            _logger.exception("Unexpected error in handshake endpoint")
+            return JSONResponse({"error": "Service unavailable"}, status_code=503)
+        return JSONResponse({"ok": True, "sdk_version": SDK_VERSION})
+
+    return router
+
+
+handshake_router = create_handshake_router()

mythos_sdk-0.1.0/mythos_sdk/jwks_cache.py

@@ -0,0 +1,40 @@
+import time
+from typing import Any
+
+import httpx
+
+CACHE_TTL = 600  # 10 minutes
+
+_cache: dict[str, Any] | None = None
+_fetched_at: float = 0.0
+
+
+def _is_stale() -> bool:
+    return _cache is None or time.monotonic() - _fetched_at > CACHE_TTL
+
+
+async def _fetch_jwks(api_url: str) -> dict[str, Any]:
+    global _cache, _fetched_at
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(f"{api_url}/.well-known/jwks.json")
+        resp.raise_for_status()
+    data: dict[str, Any] = resp.json()
+    _cache = data
+    _fetched_at = time.monotonic()
+    return data
+
+
+async def get_jwks(api_url: str, force_refresh: bool = False) -> dict[str, Any]:
+    if not force_refresh and not _is_stale() and _cache is not None:
+        return _cache
+    return await _fetch_jwks(api_url)
+
+
+async def get_jwks_with_kid_fallback(api_url: str) -> dict[str, Any]:
+    return await get_jwks(api_url, force_refresh=True)
+
+
+def clear_cache() -> None:
+    global _cache, _fetched_at
+    _cache = None
+    _fetched_at = 0.0

mythos_sdk-0.1.0/mythos_sdk/middleware.py

@@ -0,0 +1,27 @@
+from fastapi import HTTPException, Query
+
+from .api_client import consume_session
+from .types import MythosSession
+from .verify import verify_launch_token
+
+
+async def require_launch_token(lt: str = Query(..., alias="lt")) -> MythosSession:
+    try:
+        session = await verify_launch_token(lt)
+    except Exception:
+        raise HTTPException(status_code=401, detail="Invalid launch token")
+
+    try:
+        resp = await consume_session(session.sessionJti)
+    except Exception:
+        # Network error / unreachable consume endpoint — fail closed, never grant
+        # single-use access without a confirmed consume.
+        raise HTTPException(status_code=503, detail="Could not verify session")
+
+    if resp.status_code == 409:
+        raise HTTPException(status_code=401, detail="Token already consumed")
+    if not (200 <= resp.status_code < 300):
+        # Any other non-2xx (500, 503, ...) is unconfirmed — fail closed.
+        raise HTTPException(status_code=503, detail="Could not verify session")
+
+    return session

mythos_sdk-0.1.0/mythos_sdk/report_usage.py

@@ -0,0 +1,5 @@
+from .api_client import meter_session
+
+
+async def report_usage(jti: str, credits: int, reason: str | None = None) -> None:
+    await meter_session(jti, credits, reason)

mythos_sdk-0.1.0/mythos_sdk/types.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class MythosSession:
+    userId: str
+    email: str
+    displayName: str
+    listingId: str
+    sessionJti: str

mythos_sdk-0.1.0/mythos_sdk/verify.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+from jose import jwt, JWTError
+from jose.exceptions import ExpiredSignatureError, JWTClaimsError
+
+from .config import load_config
+from .jwks_cache import get_jwks, get_jwks_with_kid_fallback
+from .types import MythosSession
+
+ALGORITHMS = ["RS256"]
+_DECODE_OPTIONS = {"verify_aud": False}
+
+# Matches backend's HANDSHAKE_ISS_CLAIM constant — the platform issuer is a
+# fixed identifier, not the API URL (which varies by environment).
+MYTHOS_ISSUER = "mythos"
+
+
+def _build_session(payload: dict[str, Any]) -> MythosSession:
+    return MythosSession(
+        userId=payload["sub"],
+        email=payload["email"],
+        displayName=payload["displayName"],
+        listingId=payload["listingId"],
+        sessionJti=payload["jti"],
+    )
+
+
+def _validate_audience(payload: dict[str, Any], listing_ids: list[str]) -> None:
+    """Check all aud elements for membership — avoids aud[0]-only ordering bug."""
+    aud = payload.get("aud")
+    if aud is None:
+        raise JWTClaimsError("Missing audience claim")
+    aud_values = aud if isinstance(aud, list) else [aud]
+    if not any(a in listing_ids for a in aud_values):
+        raise JWTClaimsError("Invalid audience")
+
+
+async def verify_launch_token(token: str) -> MythosSession:
+    config = load_config()
+
+    jwks = await get_jwks(config.api_url)
+    try:
+        payload = jwt.decode(
+            token,
+            jwks,
+            algorithms=ALGORITHMS,
+            issuer=MYTHOS_ISSUER,
+            options=_DECODE_OPTIONS,
+        )
+    except JWTError as e:
+        if isinstance(e, (ExpiredSignatureError, JWTClaimsError)):
+            raise
+        # python-jose 3.x raises a bare JWTError with this message for signature
+        # failures (version pinned <4 in pyproject.toml so this text stays stable).
+        # A bad signature is not a kid miss — fail immediately, don't re-fetch JWKS.
+        if "Signature verification failed" in str(e):
+            raise
+        # possible kid miss — re-fetch once
+        jwks = await get_jwks_with_kid_fallback(config.api_url)
+        payload = jwt.decode(
+            token,
+            jwks,
+            algorithms=ALGORITHMS,
+            issuer=MYTHOS_ISSUER,
+            options=_DECODE_OPTIONS,
+        )
+
+    _validate_audience(payload, config.listing_ids)
+    return _build_session(payload)

mythos_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "cryptography>=42.0",
+    "fastapi[standard]>=0.100.0",
+    "httpx>=0.27.0",
+]
+
+[project]
+name = "mythos-sdk"
+version = "0.1.0"
+description = "Official Mythos SDK for Python — launch token verification, usage reporting, and handshake"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = [
+    "python-jose[cryptography]>=3.3.0,<4",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mythoswork/mythos-sdk"
+Repository = "https://github.com/Mythoswork/mythos-sdk"
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "cryptography>=42.0",
+    "fastapi[standard]>=0.100.0",
+    "httpx>=0.27.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+
+[[tool.mypy.overrides]]
+# python-jose ships no type stubs and types-python-jose is incomplete/unmaintained.
+module = ["jose.*"]
+ignore_missing_imports = true

mythos_sdk-0.1.0/tests/conftest.py

@@ -0,0 +1,41 @@
+import base64
+import pytest
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives import serialization
+
+
+def _int_to_base64url(n: int) -> str:
+    length = (n.bit_length() + 7) // 8
+    return base64.urlsafe_b64encode(n.to_bytes(length, "big")).rstrip(b"=").decode()
+
+
+@pytest.fixture(autouse=True)
+def set_env(monkeypatch):
+    monkeypatch.setenv("MYTHOS_LISTING_ID", "listing-abc")
+    monkeypatch.setenv("MYTHOS_API_URL", "https://api.mythos.work")
+    monkeypatch.delenv("MYTHOS_LISTING_IDS", raising=False)
+
+
+@pytest.fixture(scope="session")
+def rsa_key_pair():
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    private_pem = private_key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.TraditionalOpenSSL,
+        serialization.NoEncryption(),
+    )
+    public_key = private_key.public_key()
+    public_pem = public_key.public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    pub_numbers = public_key.public_numbers()
+    jwk = {
+        "kty": "RSA",
+        "use": "sig",
+        "alg": "RS256",
+        "kid": "test-kid",
+        "n": _int_to_base64url(pub_numbers.n),
+        "e": _int_to_base64url(pub_numbers.e),
+    }
+    return {"private": private_pem, "public": public_pem, "private_key": private_key, "jwk": jwk}

mythos_sdk-0.1.0/tests/test_api_client.py

@@ -0,0 +1,24 @@
+import re
+from unittest.mock import AsyncMock, patch
+
+import httpx
+
+from mythos_sdk.api_client import meter_session
+
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+
+
+async def test_meter_session_sends_fresh_uuid_charge_id():
+    response = httpx.Response(200, json={}, request=httpx.Request("POST", "https://api.mythos.work/"))
+    mock_post = AsyncMock(return_value=response)
+    with patch("httpx.AsyncClient.post", mock_post):
+        await meter_session("jti-001", 5, "page-view")
+        await meter_session("jti-001", 5, "page-view")
+
+    bodies = [call.kwargs["json"] for call in mock_post.await_args_list]
+
+    assert UUID_RE.match(bodies[0]["charge_id"])
+    assert UUID_RE.match(bodies[1]["charge_id"])
+    assert bodies[0]["charge_id"] != bodies[1]["charge_id"]
+    assert bodies[0]["credits"] == 5
+    assert bodies[0]["reason"] == "page-view"