stackure 1.0.0__py3-none-any.whl

stackure/__init__.py

@@ -0,0 +1,32 @@
+"""Stackure Python SDK for authentication and session management.
+
+Four public entry points:
+
+* :func:`auth` — decorator that enforces authentication on a view
+* :func:`verify` — non-throwing check that returns a :class:`VerifyResult`
+* :func:`send_magic_link` — trigger a magic-link sign-in email
+* :func:`logout` — revoke a session
+
+Plus the supporting types :class:`User`, :class:`VerifyResult`,
+:class:`MagicLinkResponse`, and the single error type :class:`StackureError`.
+
+Example:
+    >>> import stackure
+    >>> await stackure.send_magic_link(email="user@example.com", app_id="...")
+"""
+
+from .client import logout, send_magic_link
+from .errors import StackureError
+from .middleware import auth, verify
+from .types import MagicLinkResponse, User, VerifyResult
+
+__all__ = [
+    "auth",
+    "verify",
+    "send_magic_link",
+    "logout",
+    "User",
+    "VerifyResult",
+    "MagicLinkResponse",
+    "StackureError",
+]

stackure/client.py

@@ -0,0 +1,150 @@
+"""Internal HTTP layer for the Stackure SDK.
+
+Consumers should use the module-level ``send_magic_link`` and ``logout``
+functions re-exported from ``stackure``; they go through this layer.
+"""
+
+import asyncio
+import os
+
+import httpx
+
+from .errors import StackureError
+from .types import MagicLinkResponse, User
+from .validation import validate_email, validate_uuid
+
+_DEFAULT_BASE_URL = "https://stackure.com"
+_REQUEST_TIMEOUT_S = 10.0
+_MAX_RETRIES = 2
+
+
+def _base_url() -> str:
+    """Resolve the base URL from ``STACKURE_BASE_URL`` or fall back to production."""
+    env = os.environ.get("STACKURE_BASE_URL")
+    return env.rstrip("/") if env else _DEFAULT_BASE_URL
+
+
+async def _request(method: str, path: str, **kwargs) -> httpx.Response:
+    """Perform an HTTP request with retry + timeout.
+
+    Retries 5xx responses twice with exponential backoff (500ms, 1s). Timeouts
+    are never retried — a second attempt would obscure real latency.
+    """
+    url = f"{_base_url()}{path}"
+    last_error: Exception | None = None
+
+    for attempt in range(_MAX_RETRIES + 1):
+        if attempt > 0:
+            await asyncio.sleep(0.5 * (2 ** (attempt - 1)))
+        try:
+            async with httpx.AsyncClient(timeout=_REQUEST_TIMEOUT_S) as http_client:
+                response = await http_client.request(method, url, **kwargs)
+            if response.status_code >= 500 and attempt < _MAX_RETRIES:
+                last_error = StackureError(
+                    "network",
+                    f"Server error ({response.status_code})",
+                    response.status_code,
+                )
+                continue
+            return response
+        except httpx.TimeoutException as exc:
+            raise StackureError(
+                "timeout",
+                f"Request timed out after {_REQUEST_TIMEOUT_S}s",
+            ) from exc
+        except httpx.RequestError as exc:
+            last_error = StackureError("network", f"Network request failed: {exc}")
+
+    raise last_error or StackureError("network", "Request failed after retries")
+
+
+def _handle_response(response: httpx.Response) -> dict:
+    """Return parsed JSON or raise a typed :class:`StackureError` for non-2xx."""
+    if not response.is_success:
+        try:
+            error_text = response.text
+        except Exception:
+            error_text = "unknown error"
+        if response.status_code == 401:
+            raise StackureError("auth", error_text or "Authentication failed", 401)
+        if response.status_code == 403:
+            raise StackureError("forbidden", error_text or "Access forbidden", 403)
+        raise StackureError(
+            "network",
+            f"API error ({response.status_code}): {error_text}",
+            response.status_code,
+        )
+    try:
+        return response.json()
+    except Exception as exc:
+        raise StackureError("network", "Invalid JSON response from server") from exc
+
+
+async def send_magic_link(email: str, app_id: str | None = None) -> MagicLinkResponse:
+    """Send a passwordless sign-in email to a user.
+
+    Args:
+        email: Recipient's email address.
+        app_id: Your Stackure application UUID. Optional.
+
+    Returns:
+        :class:`MagicLinkResponse` with the API's confirmation message.
+
+    Raises:
+        StackureError: With ``code`` in ``{"validation", "network", "timeout", "auth"}``.
+    """
+    validate_email(email)
+    if app_id:
+        validate_uuid(app_id, "App ID")
+    body: dict = {"user_email": email}
+    if app_id:
+        body["app_id"] = app_id
+    response = await _request("POST", "/api/public/auth/magic-link/send", json=body)
+    data = _handle_response(response)
+    try:
+        return MagicLinkResponse(message=data["message"])
+    except KeyError as exc:
+        raise StackureError("network", "Unexpected API response format") from exc
+
+
+async def _validate_session(app_id: str, cookies: dict | None = None) -> dict:
+    """Internal helper: validate a session and return the raw API response dict."""
+    validate_uuid(app_id, "App ID")
+    response = await _request(
+        "GET",
+        "/api/public/auth/session/validate",
+        params={"app_id": app_id},
+        cookies=cookies,
+    )
+    data = _handle_response(response)
+    user = None
+    if data.get("user"):
+        u = data["user"]
+        try:
+            user = User(
+                user_id=u["user_id"],
+                user_email=u["user_email"],
+                user_first_name=u["user_first_name"],
+                user_last_name=u["user_last_name"],
+                user_roles=u.get("user_roles", []),
+            )
+        except KeyError as exc:
+            raise StackureError("network", "Unexpected user payload format") from exc
+    return {
+        "authenticated": data.get("authenticated", False),
+        "user": user,
+        "sign_in_url": data.get("sign_in_url"),
+    }
+
+
+async def logout(cookies: dict | None = None) -> None:
+    """Revoke the session represented by ``cookies``.
+
+    Args:
+        cookies: Cookies from the incoming HTTP request.
+
+    Raises:
+        StackureError: With ``code`` in ``{"network", "timeout"}``.
+    """
+    response = await _request("POST", "/api/public/auth/sign-out", cookies=cookies)
+    _handle_response(response)

stackure/errors.py

@@ -0,0 +1,26 @@
+"""Stackure SDK error type."""
+
+
+class StackureError(Exception):
+    """The single exception type raised by every SDK function.
+
+    Catch once and inspect ``code`` to branch on category.
+
+    Attributes:
+        code: One of ``"validation"``, ``"auth"``, ``"forbidden"``, ``"timeout"``,
+            ``"network"``.
+        status_code: HTTP status returned by the API, or ``None`` if the error
+            happened before a response was received.
+
+    Example:
+        >>> try:
+        ...     await send_magic_link(email="bad")
+        ... except StackureError as err:
+        ...     if err.code == "validation":
+        ...         ...
+    """
+
+    def __init__(self, code: str, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code

stackure/middleware.py

@@ -0,0 +1,148 @@
+"""Authentication verification and decorator for web frameworks."""
+
+import asyncio
+import functools
+import inspect
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from .client import _validate_session
+from .errors import StackureError
+from .types import VerifyResult
+
+_logger = logging.getLogger(__name__)
+
+
+async def verify(
+    app_id: str,
+    cookies: dict | None = None,
+    roles: list[str] | None = None,
+) -> VerifyResult:
+    """Check whether ``cookies`` hold a valid session for ``app_id``.
+
+    Returns a :class:`VerifyResult` without raising; callers inspect the
+    result and decide how to respond.
+
+    Args:
+        app_id: Your Stackure application UUID.
+        cookies: Session cookies from the incoming HTTP request.
+        roles: Optional required roles. The user must hold at least one.
+
+    Example:
+        >>> result = await verify(app_id="...", cookies=dict(request.cookies))
+        >>> if not result.authenticated:
+        ...     return {"error": result.error["message"]}, result.error["code"]
+        >>> return {"user": result.user}
+    """
+    try:
+        session = await _validate_session(app_id, cookies)
+        if not session["authenticated"] or not session["user"]:
+            return VerifyResult(
+                authenticated=False,
+                error={
+                    "code": 401,
+                    "message": "Valid authentication required",
+                    "sign_in_url": session["sign_in_url"],
+                },
+            )
+        user = session["user"]
+        if roles and not any(role in user.user_roles for role in roles):
+            return VerifyResult(
+                authenticated=False,
+                user=user,
+                error={"code": 403, "message": f"Requires one of: {', '.join(roles)}"},
+            )
+        return VerifyResult(authenticated=True, user=user)
+    except Exception as e:
+        _logger.error("stackure: verification error: %s", e)
+        return VerifyResult(
+            authenticated=False,
+            error={"code": 500, "message": "Authentication verification failed"},
+        )
+
+
+def _extract_cookies(request: Any) -> dict:
+    """Pull cookies off any framework's request object.
+
+    Works with FastAPI, Starlette, Flask, aiohttp (``cookies`` attr) and
+    Django (``COOKIES`` attr). Returns an empty dict if nothing is found.
+    """
+    if request is None:
+        return {}
+    cookies = getattr(request, "cookies", None) or getattr(request, "COOKIES", None)
+    return dict(cookies) if cookies else {}
+
+
+def auth(app_id: str, roles: list[str] | None = None) -> Callable:
+    """Decorator enforcing authentication on a view.
+
+    On success, attaches the authenticated :class:`~stackure.User` to
+    ``request.user`` (when the request object accepts attribute assignment).
+    On failure, raises :class:`~stackure.StackureError` — your framework's
+    exception handling turns it into the appropriate HTTP response.
+
+    Supports both synchronous and asynchronous view functions.
+
+    Args:
+        app_id: Your Stackure application UUID.
+        roles: Optional required roles.
+
+    Example:
+        >>> @app.get("/dashboard")
+        ... @auth(app_id="your-app-id", roles=["admin"])
+        ... async def dashboard(request):
+        ...     return {"user": request.user}
+    """
+
+    def decorator(func: Callable) -> Callable:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def _async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                request = args[0] if args else kwargs.get("request")
+                result = await verify(
+                    app_id,
+                    cookies=_extract_cookies(request),
+                    roles=roles,
+                )
+                if not result.authenticated:
+                    _raise(result)
+                try:
+                    request.user = result.user
+                except (AttributeError, TypeError):
+                    pass
+                return await func(*args, **kwargs)
+
+            return _async_wrapper
+
+        @functools.wraps(func)
+        def _sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            request = args[0] if args else kwargs.get("request")
+            loop = asyncio.new_event_loop()
+            try:
+                result = loop.run_until_complete(
+                    verify(app_id, cookies=_extract_cookies(request), roles=roles),
+                )
+            finally:
+                loop.close()
+            if not result.authenticated:
+                _raise(result)
+            try:
+                request.user = result.user
+            except (AttributeError, TypeError):
+                pass
+            return func(*args, **kwargs)
+
+        return _sync_wrapper
+
+    return decorator
+
+
+def _raise(result: VerifyResult) -> None:
+    """Translate a failed :class:`VerifyResult` into a :class:`StackureError`."""
+    code = result.error["code"] if result.error else 401
+    message = result.error["message"] if result.error else "Authentication required"
+    if code == 403:
+        raise StackureError("forbidden", message, 403)
+    raise StackureError("auth", message, code)

stackure/types.py

@@ -0,0 +1,52 @@
+"""Data types returned by the Stackure SDK."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class User:
+    """An authenticated Stackure user.
+
+    Attributes:
+        user_id: Unique identifier for the user.
+        user_email: User's email address.
+        user_first_name: User's first name.
+        user_last_name: User's last name.
+        user_roles: Role names assigned to the user for the current app.
+    """
+
+    user_id: str
+    user_email: str
+    user_first_name: str
+    user_last_name: str
+    user_roles: list[str] = field(default_factory=list)
+
+
+@dataclass
+class MagicLinkResponse:
+    """Successful :func:`send_magic_link` response.
+
+    Attributes:
+        message: Human-readable confirmation string from the API.
+    """
+
+    message: str
+
+
+@dataclass
+class VerifyResult:
+    """Outcome of a :func:`verify` call.
+
+    Exactly one of ``user`` or ``error`` is populated depending on
+    ``authenticated``.
+
+    Attributes:
+        authenticated: Whether the request carries a valid session.
+        user: Authenticated user when ``authenticated`` is ``True``.
+        error: Dict with ``code`` (int), ``message`` (str), and optional
+            ``sign_in_url`` when ``authenticated`` is ``False``.
+    """
+
+    authenticated: bool
+    user: User | None = None
+    error: dict | None = None

stackure/validation.py

@@ -0,0 +1,30 @@
+"""Input validation utilities for the Stackure SDK."""
+
+import re
+
+from .errors import StackureError
+
+_EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+
+def validate_email(email: str) -> None:
+    """Raise a ``"validation"``-coded :class:`StackureError` if ``email`` is malformed."""
+    if not email or not isinstance(email, str):
+        raise StackureError("validation", "email is required")
+    if not _EMAIL_RE.match(email):
+        raise StackureError("validation", "invalid email format")
+
+
+def validate_uuid(value: str, field_name: str = "UUID") -> None:
+    """Raise a ``"validation"``-coded :class:`StackureError` if ``value`` isn't a UUID v4."""
+    if not value or not isinstance(value, str):
+        raise StackureError("validation", f"{field_name} is required")
+    if not _UUID_RE.match(value):
+        raise StackureError(
+            "validation",
+            f"invalid {field_name} format (must be a valid UUID)",
+        )

stackure-1.0.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: stackure
+Version: 1.0.0
+Summary: Official Stackure authentication SDK for Python
+Project-URL: Homepage, https://stackure.com
+Project-URL: Repository, https://github.com/syi-stackure/sdk-py
+Project-URL: Documentation, https://docs.stackure.com
+Project-URL: Bug Tracker, https://github.com/syi-stackure/sdk-py/issues
+Author-email: Stackure <support@stackure.com>
+License: MIT License
+        
+        Copyright (c) 2025 ysashank
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: auth,authentication,magic-link,passwordless,sdk,sso,stackure,verify
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Description-Content-Type: text/markdown
+
+# Stackure Python SDK
+
+[![Check build](https://github.com/syi-stackure/sdk-py/actions/workflows/check-build.yml/badge.svg)](https://github.com/syi-stackure/sdk-py/actions/workflows/check-build.yml)
+[![PyPI version](https://img.shields.io/pypi/v/stackure.svg)](https://pypi.org/project/stackure/)
+[![Python versions](https://img.shields.io/pypi/pyversions/stackure.svg)](https://pypi.org/project/stackure/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/stackure.svg)](https://pypi.org/project/stackure/)
+[![Trusted publisher](https://img.shields.io/badge/pypi-trusted--publisher-blue)](https://docs.pypi.org/trusted-publishers/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Authentication for your app. One decorator.
+
+## Install
+
+```bash
+pip install stackure
+```
+
+Requires Python 3.10+.
+
+## Protect a route
+
+```python
+from stackure import auth
+
+@app.get("/admin")
+@auth(app_id="my-app-id", roles=["admin"])
+async def admin(request):
+    return {"user": request.user}
+```
+
+Works with FastAPI, Starlette, Django, Flask, aiohttp — cookies extracted automatically from the request object.
+
+## Verify manually
+
+```python
+from stackure import verify
+
+result = await verify(app_id="my-app-id", cookies=dict(request.cookies))
+
+if not result.authenticated:
+    return {"error": result.error["message"]}, result.error["code"]
+
+return {"user": result.user}
+```
+
+## Send a magic link
+
+```python
+from stackure import send_magic_link
+
+await send_magic_link(email="user@example.com", app_id="my-app-id")
+```
+
+## Log out
+
+```python
+from stackure import logout
+
+await logout(dict(request.cookies))
+```
+
+## Configuration
+
+Set `STACKURE_BASE_URL` to point at a non-production environment:
+
+```bash
+STACKURE_BASE_URL=https://stage.stackure.com python app.py
+```
+
+## Errors
+
+All errors are `StackureError`. Switch on `.code`:
+
+```python
+from stackure import StackureError
+
+try:
+    await send_magic_link(email=email)
+except StackureError as err:
+    # err.code is one of: "validation" | "auth" | "forbidden" | "timeout" | "network"
+    ...
+```
+
+## Contributing
+
+Open a PR. Tag a release when ready: `git tag vX.Y.Z && git push --tags` — the release workflow builds, signs, and publishes.
+
+## Security
+
+Report vulnerabilities via [GitHub Security Advisories](https://github.com/syi-stackure/sdk-py/security/advisories/new). Releases publish to PyPI via [OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/) with [GitHub build-provenance attestations](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+
+## License
+
+MIT

stackure-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+stackure/__init__.py,sha256=iWvXzcYR9EYzqYbsTg0p5sxDiq6Fw46apNINTmE6Y5k,931
+stackure/client.py,sha256=AltOmTvTLzdEnokbstPyisYTMTwoBJ-cjKtcoYLJNLI,5225
+stackure/errors.py,sha256=d_0bpAQXfsDZeKv-pTCKZw-PUv-W2jSWH0tJKS336BM,827
+stackure/middleware.py,sha256=pjNx65AuQOAe7cUFYo3bEelC1eAAh3RDIGAchIcHVxE,5190
+stackure/types.py,sha256=WSahy_tMhQbAyTgGRK8XwUmpQo0m5MsVemSr-4f6LJE,1319
+stackure/validation.py,sha256=yjOvrg9ljZuNKWCzy-RfR4FKn0iDBYhc8yOikAmwB9U,1069
+stackure/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stackure-1.0.0.dist-info/METADATA,sha256=IOtVa0uO1zfufp-UwdeKSnQrBbV-z4DMAl0iVoEfHaY,4978
+stackure-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stackure-1.0.0.dist-info/licenses/LICENSE,sha256=lcI5jP8yVxAC9CwlzJQi0f0mHv3Xy9ku_iJ-L8pU6ZY,1065
+stackure-1.0.0.dist-info/RECORD,,

stackure-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stackure-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ysashank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.