elav8 0.1.0__tar.gz

elav8-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/

elav8-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: elav8
+Version: 0.1.0
+Summary: Python SDK for Elav8 / Paga — Sign in with Elav8 (OAuth 2.1 + PKCE), offline token verification, entitlements, checkout/portal, and webhook verification.
+Project-URL: Homepage, https://elav8.dev
+Project-URL: Documentation, https://elav8.dev/docs
+Author: Elav8
+License-Expression: LicenseRef-Proprietary
+Keywords: billing,elav8,entitlements,jwt,oauth,oidc,paga
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# elav8 (Python SDK)
+
+Python SDK for **Elav8 / Paga** — "Sign in with Elav8" (OAuth 2.1 + PKCE),
+offline access-token verification, entitlements, hosted checkout / customer
+portal, and webhook signature verification. Mirrors the JavaScript
+[`@elav8/sdk`](https://www.npmjs.com/package/@elav8/sdk).
+
+- Offline JWT verification against Elav8's JWKS (no per-request network call).
+- One-line FastAPI route protection.
+- Small dependency surface: `PyJWT`, `cryptography`, `httpx`.
+
+## Install
+
+```bash
+pip install elav8
+# with the FastAPI helper:
+pip install "elav8[fastapi]"
+```
+
+## Verify an access token (offline)
+
+```python
+from elav8 import verify_access_token, Elav8Error
+
+try:
+    claims = verify_access_token(token, issuer="https://billing.example.com/api/auth")
+    user_id = claims["sub"]
+except Elav8Error:
+    ...  # 401
+```
+
+> Trade-off: verification is **offline**, so a token revoked before its `exp`
+> (~10 min) stays accepted until it expires. For sensitive operations, re-check
+> server state (e.g. entitlements) rather than trusting the token alone.
+
+## Protect a FastAPI route (one line)
+
+```python
+from fastapi import Depends, FastAPI
+from elav8.fastapi import require_user
+
+app = FastAPI()
+authed = require_user(issuer="https://billing.example.com/api/auth")
+
+@app.get("/me")
+def me(user: dict = Depends(authed)):
+    return {"sub": user["sub"]}
+```
+
+## Sign in with Elav8 (OAuth 2.1 + PKCE)
+
+```python
+from elav8 import Elav8OAuth
+
+oauth = Elav8OAuth(
+    issuer="https://billing.example.com/api/auth",
+    client_id="client_...",
+    redirect_uri="https://app.example.com/callback",
+)
+
+# 1. Begin sign-in — persist state + code_verifier in the session, redirect to .url
+flow = oauth.start()
+
+# 2. On your callback route:
+tokens = oauth.exchange_code(code, code_verifier)
+# tokens.access_token is a JWT verifiable with verify_access_token(...)
+```
+
+## Server API (secret key)
+
+```python
+import os
+from elav8 import Elav8ServerClient, CustomerInput
+
+elav8 = Elav8ServerClient(
+    secret_key=os.environ["ELAV8_SECRET_KEY"],
+    base_url="https://billing.example.com",
+    webhook_secret=os.environ.get("ELAV8_WEBHOOK_SECRET"),
+)
+
+snapshot = elav8.get_entitlements("user_1")
+if snapshot.entitlements.get("pro"):
+    ...
+
+checkout = elav8.create_checkout(
+    plan="pro",
+    customer=CustomerInput(email="a@b.com", external_user_id="user_1"),
+    success_url="https://app.example.com/welcome",
+    cancel_url="https://app.example.com/pricing",
+)
+# redirect the customer to checkout.url
+```
+
+## Verify a webhook
+
+```python
+event = elav8.construct_webhook_event(raw_body, signature_header)
+```
+
+Elav8 signs each webhook with `x-elav8-signature: t=<unix>,v1=<hmac-sha256-hex>`
+over `"{t}.{raw_body}"`; the timestamp blocks replays. Always pass the **raw**
+request body.
+
+## License
+
+Proprietary — internal to Elav8 until open-sourced.

elav8-0.1.0/README.md

@@ -0,0 +1,106 @@
+# elav8 (Python SDK)
+
+Python SDK for **Elav8 / Paga** — "Sign in with Elav8" (OAuth 2.1 + PKCE),
+offline access-token verification, entitlements, hosted checkout / customer
+portal, and webhook signature verification. Mirrors the JavaScript
+[`@elav8/sdk`](https://www.npmjs.com/package/@elav8/sdk).
+
+- Offline JWT verification against Elav8's JWKS (no per-request network call).
+- One-line FastAPI route protection.
+- Small dependency surface: `PyJWT`, `cryptography`, `httpx`.
+
+## Install
+
+```bash
+pip install elav8
+# with the FastAPI helper:
+pip install "elav8[fastapi]"
+```
+
+## Verify an access token (offline)
+
+```python
+from elav8 import verify_access_token, Elav8Error
+
+try:
+    claims = verify_access_token(token, issuer="https://billing.example.com/api/auth")
+    user_id = claims["sub"]
+except Elav8Error:
+    ...  # 401
+```
+
+> Trade-off: verification is **offline**, so a token revoked before its `exp`
+> (~10 min) stays accepted until it expires. For sensitive operations, re-check
+> server state (e.g. entitlements) rather than trusting the token alone.
+
+## Protect a FastAPI route (one line)
+
+```python
+from fastapi import Depends, FastAPI
+from elav8.fastapi import require_user
+
+app = FastAPI()
+authed = require_user(issuer="https://billing.example.com/api/auth")
+
+@app.get("/me")
+def me(user: dict = Depends(authed)):
+    return {"sub": user["sub"]}
+```
+
+## Sign in with Elav8 (OAuth 2.1 + PKCE)
+
+```python
+from elav8 import Elav8OAuth
+
+oauth = Elav8OAuth(
+    issuer="https://billing.example.com/api/auth",
+    client_id="client_...",
+    redirect_uri="https://app.example.com/callback",
+)
+
+# 1. Begin sign-in — persist state + code_verifier in the session, redirect to .url
+flow = oauth.start()
+
+# 2. On your callback route:
+tokens = oauth.exchange_code(code, code_verifier)
+# tokens.access_token is a JWT verifiable with verify_access_token(...)
+```
+
+## Server API (secret key)
+
+```python
+import os
+from elav8 import Elav8ServerClient, CustomerInput
+
+elav8 = Elav8ServerClient(
+    secret_key=os.environ["ELAV8_SECRET_KEY"],
+    base_url="https://billing.example.com",
+    webhook_secret=os.environ.get("ELAV8_WEBHOOK_SECRET"),
+)
+
+snapshot = elav8.get_entitlements("user_1")
+if snapshot.entitlements.get("pro"):
+    ...
+
+checkout = elav8.create_checkout(
+    plan="pro",
+    customer=CustomerInput(email="a@b.com", external_user_id="user_1"),
+    success_url="https://app.example.com/welcome",
+    cancel_url="https://app.example.com/pricing",
+)
+# redirect the customer to checkout.url
+```
+
+## Verify a webhook
+
+```python
+event = elav8.construct_webhook_event(raw_body, signature_header)
+```
+
+Elav8 signs each webhook with `x-elav8-signature: t=<unix>,v1=<hmac-sha256-hex>`
+over `"{t}.{raw_body}"`; the timestamp blocks replays. Always pass the **raw**
+request body.
+
+## License
+
+Proprietary — internal to Elav8 until open-sourced.

elav8-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elav8"
+version = "0.1.0"
+description = "Python SDK for Elav8 / Paga — Sign in with Elav8 (OAuth 2.1 + PKCE), offline token verification, entitlements, checkout/portal, and webhook verification."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Elav8" }]
+keywords = ["elav8", "paga", "oauth", "oidc", "billing", "entitlements", "jwt"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "pyjwt[crypto]>=2.8",
+  "cryptography>=42.0",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "mypy>=1.8",
+  "ruff>=0.5",
+  "fastapi>=0.110",
+]
+
+[project.urls]
+Homepage = "https://elav8.dev"
+Documentation = "https://elav8.dev/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/elav8"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/elav8", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+# Type-check against 3.10 (the lowest version this mypy supports); the package
+# still runs on 3.9+ at runtime (annotations are deferred via __future__).
+[tool.mypy]
+python_version = "3.10"
+strict = true

elav8-0.1.0/src/elav8/__init__.py

@@ -0,0 +1,75 @@
+"""Elav8 / Paga Python SDK.
+
+Mirrors ``@elav8/sdk`` (JavaScript): "Sign in with Elav8" (OAuth 2.1 + PKCE),
+offline access-token verification, entitlements, hosted checkout / portal, and
+webhook signature verification.
+
+``elav8.fastapi`` (extra ``elav8[fastapi]``) adds a one-line ``require_user``
+route dependency.
+"""
+
+from __future__ import annotations
+
+from ._types import (
+    AccessTokenClaims,
+    CheckoutResult,
+    CustomerInput,
+    Elav8User,
+    EntitlementSnapshot,
+    Plan,
+)
+from .client import Elav8ServerClient
+from .errors import Elav8Error
+from .oauth import (
+    Elav8OAuth,
+    SignInRedirect,
+    TokenResponse,
+    build_authorize_url,
+    build_refresh_form,
+    build_token_exchange_form,
+)
+from .pkce import (
+    PkcePair,
+    create_code_challenge,
+    create_pkce_pair,
+    generate_code_verifier,
+    generate_state,
+)
+from .verify import verify_access_token
+from .webhook import construct_webhook_event, sign_payload, verify_webhook_signature
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Errors
+    "Elav8Error",
+    # Types
+    "AccessTokenClaims",
+    "CheckoutResult",
+    "CustomerInput",
+    "Elav8User",
+    "EntitlementSnapshot",
+    "Plan",
+    # Server client
+    "Elav8ServerClient",
+    # OAuth
+    "Elav8OAuth",
+    "SignInRedirect",
+    "TokenResponse",
+    "build_authorize_url",
+    "build_refresh_form",
+    "build_token_exchange_form",
+    # PKCE
+    "PkcePair",
+    "create_code_challenge",
+    "create_pkce_pair",
+    "generate_code_verifier",
+    "generate_state",
+    # Verify
+    "verify_access_token",
+    # Webhooks
+    "construct_webhook_event",
+    "sign_payload",
+    "verify_webhook_signature",
+]

elav8-0.1.0/src/elav8/_types.py

@@ -0,0 +1,99 @@
+"""Typed data shapes mirroring ``packages/sdk/src/shared.ts``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Union
+
+EntitlementValue = Union[bool, int, float, str, None]
+
+
+@dataclass
+class Plan:
+    id: str
+    slug: str
+    name: str
+
+
+@dataclass
+class EntitlementSnapshot:
+    """A resolved entitlements snapshot for a customer of an app."""
+
+    active: bool
+    plan: Optional[Plan]
+    subscription_status: Optional[str]
+    current_period_end: Optional[str]
+    cancel_at_period_end: bool
+    entitlements: Dict[str, EntitlementValue] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "EntitlementSnapshot":
+        plan_data = data.get("plan")
+        return cls(
+            active=bool(data.get("active", False)),
+            plan=Plan(**plan_data) if plan_data else None,
+            subscription_status=data.get("subscriptionStatus"),
+            current_period_end=data.get("currentPeriodEnd"),
+            cancel_at_period_end=bool(data.get("cancelAtPeriodEnd", False)),
+            entitlements=data.get("entitlements") or {},
+        )
+
+
+@dataclass
+class Elav8User:
+    """The minimal user shape returned by the OIDC UserInfo endpoint."""
+
+    sub: str
+    email: Optional[str] = None
+    email_verified: Optional[bool] = None
+    name: Optional[str] = None
+    picture: Optional[str] = None
+    claims: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "Elav8User":
+        known = {"sub", "email", "email_verified", "name", "picture"}
+        return cls(
+            sub=str(data.get("sub", "")),
+            email=data.get("email"),
+            email_verified=data.get("email_verified"),
+            name=data.get("name"),
+            picture=data.get("picture"),
+            claims={k: v for k, v in data.items() if k not in known},
+        )
+
+
+# Verified access-token claims (parity with AccessTokenClaims in verify.ts).
+AccessTokenClaims = Dict[str, Any]
+
+
+@dataclass
+class CheckoutResult:
+    url: str
+    session_id: str
+
+
+@dataclass
+class CustomerInput:
+    email: str
+    external_user_id: Optional[str] = None
+    name: Optional[str] = None
+
+    def to_api(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"email": self.email}
+        if self.external_user_id is not None:
+            out["externalUserId"] = self.external_user_id
+        if self.name is not None:
+            out["name"] = self.name
+        return out
+
+
+__all__ = [
+    "Plan",
+    "EntitlementSnapshot",
+    "Elav8User",
+    "AccessTokenClaims",
+    "CheckoutResult",
+    "CustomerInput",
+    "EntitlementValue",
+]

elav8-0.1.0/src/elav8/client.py

@@ -0,0 +1,178 @@
+"""Server-side Elav8 client — parity with ``packages/sdk/src/server.ts``.
+
+Uses your **secret** key (``elav8_sk_...``) as a Bearer token to call the Elav8
+API: create checkout sessions, create customer-portal links, read entitlements,
+verify access tokens offline, and verify forwarded webhooks.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from ._types import CheckoutResult, CustomerInput, EntitlementSnapshot
+from .errors import Elav8Error
+from .verify import verify_access_token
+from .webhook import construct_webhook_event, verify_webhook_signature
+
+
+def _trim_trailing_slash(value: str) -> str:
+    return value[:-1] if value.endswith("/") else value
+
+
+class Elav8ServerClient:
+    """Server-only Elav8 client authenticated with your secret key.
+
+    Example::
+
+        elav8 = Elav8ServerClient(
+            secret_key=os.environ["ELAV8_SECRET_KEY"],
+            base_url="https://billing.example.com",
+        )
+        snapshot = elav8.get_entitlements("user_1")
+        if snapshot.entitlements.get("pro"):
+            ...
+    """
+
+    def __init__(
+        self,
+        *,
+        secret_key: str,
+        base_url: str,
+        webhook_secret: Optional[str] = None,
+        issuer: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self._secret_key = secret_key
+        self._base = _trim_trailing_slash(base_url)
+        self._webhook_secret = webhook_secret
+        self._issuer = _trim_trailing_slash(issuer or f"{self._base}/api/auth")
+        self._client = http_client
+        self._timeout = timeout
+
+    # -- HTTP ---------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        owns_client = self._client is None
+        client = self._client or httpx.Client(timeout=self._timeout)
+        try:
+            res = client.request(
+                method,
+                f"{self._base}{path}",
+                json=json,
+                params=params,
+                headers={
+                    "authorization": f"Bearer {self._secret_key}",
+                    "accept": "application/json",
+                },
+            )
+        finally:
+            if owns_client:
+                client.close()
+        if res.status_code >= 400:
+            raise _error_from_response(res)
+        return res.json() if res.content else {}
+
+    # -- Billing ------------------------------------------------------------
+
+    def create_checkout(
+        self,
+        *,
+        plan: str,
+        customer: Union[CustomerInput, Dict[str, Any]],
+        success_url: str,
+        cancel_url: str,
+        price_id: Optional[str] = None,
+        trial_days: Optional[int] = None,
+    ) -> CheckoutResult:
+        body: Dict[str, Any] = {
+            "plan": plan,
+            "customer": customer.to_api() if isinstance(customer, CustomerInput) else customer,
+            "successUrl": success_url,
+            "cancelUrl": cancel_url,
+        }
+        if price_id is not None:
+            body["priceId"] = price_id
+        if trial_days is not None:
+            body["trialDays"] = trial_days
+        data = self._request("POST", "/api/v1/checkout", json=body)
+        return CheckoutResult(url=data["checkoutUrl"], session_id=data["sessionId"])
+
+    def create_portal_link(
+        self, *, customer: Union[CustomerInput, Dict[str, Any]], return_url: str
+    ) -> str:
+        cust = customer.to_api() if isinstance(customer, CustomerInput) else customer
+        data = self._request(
+            "POST", "/api/v1/portal", json={"customer": cust, "returnUrl": return_url}
+        )
+        return str(data["portalUrl"])
+
+    def get_entitlements(
+        self, external_user_id: str, *, by_email: bool = False
+    ) -> EntitlementSnapshot:
+        params = {"email": external_user_id} if by_email else {"externalUserId": external_user_id}
+        data = self._request("GET", "/api/v1/entitlements", params=params)
+        return EntitlementSnapshot.from_api(data)
+
+    # -- Auth ---------------------------------------------------------------
+
+    def verify_access_token(
+        self,
+        token: str,
+        *,
+        audience: Optional[Union[str, List[str]]] = None,
+        leeway: int = 60,
+    ) -> Dict[str, Any]:
+        """Verifies a JWT access token offline against Elav8's JWKS.
+
+        Note: a token revoked before ``exp`` (~10 min) stays valid until then;
+        re-check server state for sensitive operations.
+        """
+        return verify_access_token(
+            token, issuer=self._issuer, audience=audience, leeway=leeway
+        )
+
+    # -- Webhooks -----------------------------------------------------------
+
+    def _require_webhook_secret(self) -> str:
+        if not self._webhook_secret:
+            raise Elav8Error(
+                "webhook_secret is required to verify webhooks.", 0, "missing_webhook_secret"
+            )
+        return self._webhook_secret
+
+    def verify_webhook(self, payload: Union[str, bytes], signature: str) -> bool:
+        return verify_webhook_signature(payload, signature, self._require_webhook_secret())
+
+    def construct_webhook_event(
+        self, payload: Union[str, bytes], signature: str
+    ) -> Dict[str, Any]:
+        return construct_webhook_event(payload, signature, self._require_webhook_secret())
+
+
+def _error_from_response(res: httpx.Response) -> Elav8Error:
+    try:
+        body = res.json()
+    except ValueError:
+        body = {}
+    message = (
+        body.get("error_description")
+        or body.get("title")
+        or body.get("detail")
+        or body.get("error")
+        or f"Request failed with status {res.status_code}"
+    )
+    code = body.get("code") or body.get("error") or "elav8_error"
+    return Elav8Error(message, res.status_code, code, body)
+
+
+__all__ = ["Elav8ServerClient"]

elav8-0.1.0/src/elav8/errors.py

@@ -0,0 +1,29 @@
+"""Structured error type, mirroring the JS SDK's ``Elav8Error``."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class Elav8Error(Exception):
+    """Raised on any SDK failure (HTTP non-2xx, invalid token, bad signature).
+
+    Mirrors ``Elav8Error`` in ``@elav8/sdk`` so error handling looks the same
+    across languages.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        code: str = "elav8_error",
+        details: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"Elav8Error(message={self.message!r}, status={self.status}, code={self.code!r})"

elav8-0.1.0/src/elav8/fastapi.py

@@ -0,0 +1,70 @@
+"""FastAPI integration — protect a route with one line.
+
+Example::
+
+    from fastapi import Depends, FastAPI
+    from elav8.fastapi import require_user
+
+    app = FastAPI()
+    authed = require_user(issuer="https://billing.example.com/api/auth")
+
+    @app.get("/me")
+    def me(user: dict = Depends(authed)):
+        return {"sub": user["sub"]}
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .errors import Elav8Error
+from .verify import verify_access_token
+
+try:
+    from fastapi import Depends, HTTPException
+    from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+except ImportError as exc:  # pragma: no cover - import-time guard
+    raise ImportError(
+        "elav8.fastapi requires FastAPI. Install it with: pip install 'elav8[fastapi]'"
+    ) from exc
+
+
+def require_user(
+    *,
+    issuer: str,
+    audience: Optional[Union[str, List[str]]] = None,
+    leeway: int = 60,
+) -> Callable[..., Dict[str, Any]]:
+    """Builds a FastAPI dependency that authenticates the request via a Bearer
+    JWT access token and returns its verified claims.
+
+    Verification is offline (against ``{issuer}/jwks``), so it adds no network
+    latency per request. Raises ``HTTPException(401)`` when the token is missing,
+    malformed, expired, or otherwise invalid.
+    """
+    bearer_scheme = HTTPBearer(auto_error=False)
+
+    def dependency(
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(bearer_scheme),
+    ) -> Dict[str, Any]:
+        if credentials is None or not credentials.credentials:
+            raise HTTPException(
+                status_code=401,
+                detail="Missing bearer token.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        try:
+            return verify_access_token(
+                credentials.credentials, issuer=issuer, audience=audience, leeway=leeway
+            )
+        except Elav8Error as exc:
+            raise HTTPException(
+                status_code=401,
+                detail=exc.message,
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from exc
+
+    return dependency
+
+
+__all__ = ["require_user"]

elav8-0.1.0/src/elav8/oauth.py

@@ -0,0 +1,234 @@
+"""OAuth 2.1 + PKCE sign-in helpers — parity with ``packages/sdk/src/url.ts``
+and the token-exchange flow in ``index.ts``.
+
+Pure URL/form builders are kept separate from HTTP so the exact request shape is
+testable, then wrapped by :class:`Elav8OAuth` which performs the exchange.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from .errors import Elav8Error
+from .pkce import PkcePair, create_pkce_pair, generate_state
+
+DEFAULT_SCOPES = ["openid", "profile", "email"]
+
+
+def _trim_trailing_slash(value: str) -> str:
+    return value[:-1] if value.endswith("/") else value
+
+
+def build_authorize_url(
+    *,
+    issuer: str,
+    client_id: str,
+    redirect_uri: str,
+    code_challenge: str,
+    state: str,
+    scopes: Optional[List[str]] = None,
+    prompt: Optional[str] = None,
+) -> str:
+    """Builds the ``/oauth2/authorize`` URL with PKCE (S256)."""
+    params: Dict[str, str] = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(scopes or DEFAULT_SCOPES),
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    if prompt:
+        params["prompt"] = prompt
+    return f"{_trim_trailing_slash(issuer)}/oauth2/authorize?{urlencode(params)}"
+
+
+def build_token_exchange_form(
+    *,
+    client_id: str,
+    code: str,
+    redirect_uri: str,
+    code_verifier: str,
+    resource: Optional[str] = None,
+) -> Dict[str, str]:
+    """Builds the authorization-code grant body (public client; no secret).
+
+    When ``resource`` is set (to the issuer), the provider returns a signed JWT
+    access token verifiable offline via ``/jwks`` instead of an opaque token.
+    """
+    form = {
+        "grant_type": "authorization_code",
+        "client_id": client_id,
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "code_verifier": code_verifier,
+    }
+    if resource:
+        form["resource"] = resource
+    return form
+
+
+def build_refresh_form(
+    client_id: str, refresh_token: str, resource: Optional[str] = None
+) -> Dict[str, str]:
+    """Builds the refresh-token grant body (public client)."""
+    form = {
+        "grant_type": "refresh_token",
+        "client_id": client_id,
+        "refresh_token": refresh_token,
+    }
+    if resource:
+        form["resource"] = resource
+    return form
+
+
+@dataclass
+class TokenResponse:
+    access_token: str
+    token_type: str = "Bearer"
+    expires_in: Optional[int] = None
+    refresh_token: Optional[str] = None
+    id_token: Optional[str] = None
+    scope: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> "TokenResponse":
+        return cls(
+            access_token=str(data["access_token"]),
+            token_type=data.get("token_type", "Bearer"),
+            expires_in=data.get("expires_in"),
+            refresh_token=data.get("refresh_token"),
+            id_token=data.get("id_token"),
+            scope=data.get("scope"),
+            raw=data,
+        )
+
+
+@dataclass
+class SignInRedirect:
+    """What you need to begin sign-in: the URL to redirect to, plus the PKCE
+    verifier and state to stash in the user's session for the callback."""
+
+    url: str
+    state: str
+    code_verifier: str
+
+
+class Elav8OAuth:
+    """Server-side helper for "Sign in with Elav8" (OAuth 2.1 + PKCE).
+
+    Example (FastAPI)::
+
+        oauth = Elav8OAuth(
+            issuer="https://billing.example.com/api/auth",
+            client_id="client_...",
+            redirect_uri="https://app.example.com/callback",
+        )
+        # 1. Begin sign-in:
+        flow = oauth.start()
+        # persist flow.state + flow.code_verifier, then redirect to flow.url
+        # 2. On the callback:
+        tokens = oauth.exchange_code(code, code_verifier)
+    """
+
+    def __init__(
+        self,
+        *,
+        issuer: str,
+        client_id: str,
+        redirect_uri: str,
+        scopes: Optional[List[str]] = None,
+        request_jwt_access_token: bool = True,
+        http_client: Optional[httpx.Client] = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.issuer = _trim_trailing_slash(issuer)
+        self.client_id = client_id
+        self.redirect_uri = redirect_uri
+        self.scopes = scopes or DEFAULT_SCOPES
+        # Request the issuer as the audience so access tokens are JWTs.
+        self._resource = self.issuer if request_jwt_access_token else None
+        self._client = http_client
+        self._timeout = timeout
+
+    def _http(self) -> httpx.Client:
+        return self._client or httpx.Client(timeout=self._timeout)
+
+    def start(
+        self, *, state: Optional[str] = None, prompt: Optional[str] = None
+    ) -> SignInRedirect:
+        pair: PkcePair = create_pkce_pair()
+        st = state or generate_state()
+        url = build_authorize_url(
+            issuer=self.issuer,
+            client_id=self.client_id,
+            redirect_uri=self.redirect_uri,
+            code_challenge=pair.challenge,
+            state=st,
+            scopes=self.scopes,
+            prompt=prompt,
+        )
+        return SignInRedirect(url=url, state=st, code_verifier=pair.verifier)
+
+    def exchange_code(self, code: str, code_verifier: str) -> TokenResponse:
+        form = build_token_exchange_form(
+            client_id=self.client_id,
+            code=code,
+            redirect_uri=self.redirect_uri,
+            code_verifier=code_verifier,
+            resource=self._resource,
+        )
+        return self._post_token(form)
+
+    def refresh(self, refresh_token: str) -> TokenResponse:
+        form = build_refresh_form(self.client_id, refresh_token, self._resource)
+        return self._post_token(form)
+
+    def _post_token(self, form: Dict[str, str]) -> TokenResponse:
+        owns_client = self._client is None
+        client = self._http()
+        try:
+            res = client.post(
+                f"{self.issuer}/oauth2/token",
+                data=form,
+                headers={"accept": "application/json"},
+            )
+        finally:
+            if owns_client:
+                client.close()
+        if res.status_code >= 400:
+            raise _error_from_response(res)
+        return TokenResponse.from_api(res.json())
+
+
+def _error_from_response(res: httpx.Response) -> Elav8Error:
+    try:
+        body = res.json()
+    except ValueError:
+        body = {}
+    message = (
+        body.get("error_description")
+        or body.get("title")
+        or body.get("detail")
+        or body.get("error")
+        or f"Request failed with status {res.status_code}"
+    )
+    code = body.get("code") or body.get("error") or "elav8_error"
+    return Elav8Error(message, res.status_code, code, body)
+
+
+__all__ = [
+    "DEFAULT_SCOPES",
+    "build_authorize_url",
+    "build_token_exchange_form",
+    "build_refresh_form",
+    "TokenResponse",
+    "SignInRedirect",
+    "Elav8OAuth",
+]

elav8-0.1.0/src/elav8/pkce.py

@@ -0,0 +1,56 @@
+"""PKCE (RFC 7636) helpers — parity with ``packages/sdk/src/pkce.ts``.
+
+The code challenge method is always ``S256`` (the insecure ``plain`` method is
+never used), matching OAuth 2.1.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from dataclasses import dataclass
+
+
+def base64url_encode(data: bytes) -> str:
+    """Base64url-encodes bytes without padding (RFC 7636 Appendix A)."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_code_verifier(byte_length: int = 32) -> str:
+    """Generates a high-entropy code verifier (43-128 chars per the spec)."""
+    return base64url_encode(os.urandom(byte_length))
+
+
+def create_code_challenge(verifier: str) -> str:
+    """Derives the S256 code challenge from a verifier."""
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64url_encode(digest)
+
+
+def generate_state() -> str:
+    """Generates an opaque random value for the OAuth ``state`` parameter."""
+    return generate_code_verifier(16)
+
+
+@dataclass
+class PkcePair:
+    verifier: str
+    challenge: str
+    method: str = "S256"
+
+
+def create_pkce_pair() -> PkcePair:
+    """Creates a verifier + S256 challenge pair ready for the authorize request."""
+    verifier = generate_code_verifier()
+    return PkcePair(verifier=verifier, challenge=create_code_challenge(verifier))
+
+
+__all__ = [
+    "base64url_encode",
+    "generate_code_verifier",
+    "create_code_challenge",
+    "generate_state",
+    "PkcePair",
+    "create_pkce_pair",
+]

elav8-0.1.0/src/elav8/verify.py

@@ -0,0 +1,95 @@
+"""Offline access-token verification — parity with ``packages/sdk/src/verify.ts``.
+
+Elav8 issues EdDSA-signed JWT access tokens (when the token request includes the
+issuer as its ``resource``/audience). This verifies the signature against the
+published JWKS (``/jwks``) plus issuer, audience, and expiry, using PyJWT's
+``PyJWKClient`` for key fetching, caching, and rotation.
+
+Trade-off: verification is offline, so a token revoked before its ``exp``
+(~10 minutes) stays accepted until it expires. For sensitive operations,
+re-check server state (e.g. entitlements) rather than trusting the token alone.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import List, Optional, Union
+
+import jwt
+from jwt import PyJWKClient
+
+from ._types import AccessTokenClaims
+from .errors import Elav8Error
+
+# JWKS cache lifetime; after this the client refetches keys (handles rotation).
+_JWKS_LIFESPAN_SECONDS = 300
+
+
+def _trim_trailing_slash(value: str) -> str:
+    return value[:-1] if value.endswith("/") else value
+
+
+@lru_cache(maxsize=32)
+def _shared_jwk_client(jwks_url: str) -> PyJWKClient:
+    return PyJWKClient(jwks_url, cache_keys=True, lifespan=_JWKS_LIFESPAN_SECONDS)
+
+
+def verify_access_token(
+    token: str,
+    *,
+    issuer: str,
+    audience: Optional[Union[str, List[str]]] = None,
+    jwks_url: Optional[str] = None,
+    leeway: int = 60,
+    jwk_client: Optional[PyJWKClient] = None,
+) -> AccessTokenClaims:
+    """Verifies an EdDSA JWT access token and returns its claims.
+
+    Raises :class:`~elav8.errors.Elav8Error` (status 401) on any failure.
+
+    :param issuer: Expected issuer, e.g. ``https://billing.example.com/api/auth``.
+        Also used to derive the JWKS URL and the default expected audience.
+    :param audience: Expected audience(s); defaults to ``issuer``.
+    :param jwks_url: Override the JWKS URL (defaults to ``{issuer}/jwks``).
+    :param leeway: Allowable clock skew in seconds (default 60).
+    :param jwk_client: Reuse an existing ``PyJWKClient`` (keeps the cache warm).
+    """
+    issuer = _trim_trailing_slash(issuer)
+    client = jwk_client or _shared_jwk_client(jwks_url or f"{issuer}/jwks")
+
+    try:
+        signing_key = client.get_signing_key_from_jwt(token)
+    except jwt.PyJWTError as exc:
+        raise Elav8Error(
+            "No matching JWKS key for the token.", 401, "jwks_key_not_found", str(exc)
+        ) from exc
+    except Exception as exc:  # network / fetch failures from urllib
+        raise Elav8Error("Failed to fetch JWKS.", 401, "jwks_fetch_failed", str(exc)) from exc
+
+    expected_audience: Union[str, List[str]] = audience if audience is not None else issuer
+
+    try:
+        claims = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["EdDSA"],
+            issuer=issuer,
+            audience=expected_audience,
+            leeway=leeway,
+            options={"require": ["exp", "iss", "sub"]},
+        )
+    except jwt.ExpiredSignatureError as exc:
+        raise Elav8Error("Access token has expired.", 401, "token_expired", str(exc)) from exc
+    except jwt.InvalidAudienceError as exc:
+        raise Elav8Error("Token audience mismatch.", 401, "invalid_audience", str(exc)) from exc
+    except jwt.InvalidIssuerError as exc:
+        raise Elav8Error("Token issuer mismatch.", 401, "invalid_issuer", str(exc)) from exc
+    except jwt.InvalidSignatureError as exc:
+        raise Elav8Error("Invalid access token signature.", 401, "invalid_signature", str(exc)) from exc
+    except jwt.PyJWTError as exc:
+        raise Elav8Error("Invalid access token.", 401, "invalid_token", str(exc)) from exc
+
+    return claims
+
+
+__all__ = ["verify_access_token"]

elav8-0.1.0/src/elav8/webhook.py

@@ -0,0 +1,107 @@
+"""Webhook signature verification — parity with ``packages/sdk/src/webhook.ts``.
+
+Elav8 signs each forwarded webhook with your app's webhook secret and sends a
+timestamped HMAC-SHA256 signature in the ``x-elav8-signature`` header:
+
+    x-elav8-signature: t=<unix_seconds>,v1=<hex_hmac>
+
+The signed content is ``"{t}.{raw_body}"``. Including the timestamp (and
+rejecting old ones) blocks replay attacks. Always verify before trusting an
+event, and pass the **raw** request body (not a re-serialized object).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional, Tuple, Union
+
+from .errors import Elav8Error
+
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def _to_bytes(value: Union[str, bytes]) -> bytes:
+    return value if isinstance(value, bytes) else value.encode("utf-8")
+
+
+def _compute(timestamp: int, payload: Union[str, bytes], secret: str) -> str:
+    signed = b"%d." % timestamp + _to_bytes(payload)
+    return hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+
+
+def sign_payload(
+    payload: Union[str, bytes], secret: str, *, timestamp: Optional[int] = None
+) -> str:
+    """Produces the ``t=<ts>,v1=<hex>`` header value for ``payload``.
+
+    Primarily for tests / parity; senders are in the Elav8 backend.
+    """
+    ts = int(timestamp if timestamp is not None else time.time())
+    return f"t={ts},v1={_compute(ts, payload, secret)}"
+
+
+def _parse_header(header: str) -> Tuple[Optional[int], Optional[str]]:
+    timestamp: Optional[int] = None
+    signature: Optional[str] = None
+    for part in header.split(","):
+        key, _, value = part.strip().partition("=")
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                timestamp = None
+        elif key == "v1":
+            signature = value.strip().lower()
+    return timestamp, signature
+
+
+def verify_webhook_signature(
+    payload: Union[str, bytes],
+    signature_header: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+) -> bool:
+    """Returns ``True`` when the signature is valid and within the time window."""
+    timestamp, signature = _parse_header(signature_header)
+    if timestamp is None or not signature:
+        return False
+    if tolerance_seconds > 0 and abs(int(time.time()) - timestamp) > tolerance_seconds:
+        return False
+    expected = _compute(timestamp, payload, secret)
+    return hmac.compare_digest(expected, signature)
+
+
+def construct_webhook_event(
+    payload: Union[str, bytes],
+    signature_header: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+) -> Dict[str, Any]:
+    """Verifies the signature and returns the parsed event.
+
+    Raises :class:`~elav8.errors.Elav8Error` if the signature is invalid/expired
+    or the body is not JSON.
+    """
+    if not verify_webhook_signature(
+        payload, signature_header, secret, tolerance_seconds=tolerance_seconds
+    ):
+        raise Elav8Error("Invalid webhook signature.", 400, "invalid_signature")
+    try:
+        text = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+        event: Dict[str, Any] = json.loads(text)
+        return event
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise Elav8Error("Webhook payload is not valid JSON.", 400, "invalid_payload") from exc
+
+
+__all__ = [
+    "DEFAULT_TOLERANCE_SECONDS",
+    "sign_payload",
+    "verify_webhook_signature",
+    "construct_webhook_event",
+]