datagrowth-common 0.3.2__py3-none-any.whl

datagrowth_common/__init__.py

@@ -0,0 +1,83 @@
+"""datagrowth-common — utilidades compartidas entre apps Datagrowth.
+
+v0.3.1 (mayo 2026):
+- Nuevo subpaquete `datagrowth_common.ui`: Jinja2 partials (`dg/...`),
+  tokens CSS con tema light/dark, Tailwind precompilado y JS de theme/
+  toasts/htmx-events. Helper `register_ui(app, jinja_env, mount_path)`
+  para inyectar todo en una FastAPI host app.
+
+v0.3.0 (mayo 2026, BREAKING):
+- Eliminados `datagrowth_common.authentik` y `datagrowth_common.auth_fastapi`
+  (forward-auth basado en Authentik). Importarlos lanza `ImportError`.
+- `datagrowth_common.auth.local` renombrado a `datagrowth_common.auth.session_hmac`.
+  Se eliminó toda la integración con Authentik OIDC (password_login, refresh,
+  userinfo, start_oidc, oidc_callback, register_local, magic_link_request,
+  password_reset, TokenPair, OidcStart). Solo se conserva la cookie HMAC.
+  `auth.local` queda como alias deprecated (DeprecationWarning); eliminado en v0.4.0.
+- Modelo único de auth: Supabase Auth (cookie JWT en `auth.session` +
+  endpoints en `auth.router` + verify en `auth.supabase`).
+
+v0.2.2 (anterior):
+- `auth.supabase_admin` añadidos `create_user_with_password` y
+  `send_password_reset` para flujos de gestión de usuarios end-to-end.
+
+Ver CHANGELOG.md para la guía de migración completa.
+"""
+from .auth.supabase import (
+    SupabaseUser,
+    SupabaseUserDep,
+    require_role,
+    require_supabase_jwt,
+    verify_supabase_jwt,
+)
+from .auth.session import (
+    ACCESS_COOKIE,
+    REFRESH_COOKIE,
+    SessionTokens,
+    SessionUserDep,
+    clear_session,
+    get_session_tokens,
+    refresh_session_tokens,
+    require_session,
+    set_session,
+)
+from .auth.router import auth_router, make_auth_router
+from .api.users import users_router
+from .result import Result, ok, err
+from .logger import get_logger, setup_logging
+from .ui import UI_VERSION, register_ui
+
+__version__ = "0.3.2"
+
+__all__ = [
+    # supabase auth (JWT)
+    "SupabaseUser",
+    "SupabaseUserDep",
+    "require_role",
+    "require_supabase_jwt",
+    "verify_supabase_jwt",
+    "users_router",
+    # session (cookie httpOnly server-rendered)
+    "ACCESS_COOKIE",
+    "REFRESH_COOKIE",
+    "SessionTokens",
+    "SessionUserDep",
+    "set_session",
+    "clear_session",
+    "get_session_tokens",
+    "refresh_session_tokens",
+    "require_session",
+    # auth router (login + OAuth + refresh + logout)
+    "auth_router",
+    "make_auth_router",
+    # core
+    "Result",
+    "ok",
+    "err",
+    "get_logger",
+    "setup_logging",
+    # ui (datagrowth_common.ui)
+    "register_ui",
+    "UI_VERSION",
+    "__version__",
+]

datagrowth_common/api/__init__.py

@@ -0,0 +1,20 @@
+"""API helpers compartidos: respuesta estandar y paginacion.
+
+Para `users_router` (CRUD sobre Supabase Admin API), importar
+explicitamente: `from datagrowth_common.api.users import users_router`.
+Se evita re-exportarlo aqui para no forzar el import de
+`auth.supabase` cuando un consumidor solo necesita helpers genericos.
+"""
+from .errors import ApiResponse, ErrorBody, ErrorCode, err_response, ok_response
+from .pagination import PageMeta, Paginated, paginate_params
+
+__all__ = [
+    "ApiResponse",
+    "ErrorBody",
+    "ErrorCode",
+    "err_response",
+    "ok_response",
+    "PageMeta",
+    "Paginated",
+    "paginate_params",
+]

datagrowth_common/api/errors.py

@@ -0,0 +1,63 @@
+"""Respuesta estandar `ApiResponse` y catalogo de errores.
+
+Codigo y mensaje van siempre en `error`. Los handlers nunca lanzan
+excepciones a traves de la frontera HTTP: devuelven `ApiResponse` con
+`error` poblado o `data` poblado, exclusivo.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, Field, model_validator
+
+T = TypeVar("T")
+
+
+class ErrorCode(str, Enum):
+    NOT_FOUND = "NOT_FOUND"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    RATE_LIMITED = "RATE_LIMITED"
+    CONFLICT = "CONFLICT"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class ErrorBody(BaseModel):
+    code: ErrorCode
+    message: str
+    details: dict[str, Any] | None = None
+
+
+class ApiResponse(BaseModel, Generic[T]):
+    data: T | None = None
+    error: ErrorBody | None = None
+    meta: dict[str, Any] | None = Field(default=None)
+
+    @model_validator(mode="after")
+    def _xor_data_error(self) -> "ApiResponse[T]":
+        if (self.data is None) == (self.error is None):
+            raise ValueError("ApiResponse requires exactly one of data|error")
+        return self
+
+
+def ok_response(data: T, meta: dict[str, Any] | None = None) -> ApiResponse[T]:
+    return ApiResponse[T](data=data, meta=meta)
+
+
+def err_response(
+    code: ErrorCode, message: str, details: dict[str, Any] | None = None,
+) -> ApiResponse[Any]:
+    return ApiResponse[Any](error=ErrorBody(code=code, message=message, details=details))
+
+
+HTTP_STATUS_FOR_CODE: dict[ErrorCode, int] = {
+    ErrorCode.NOT_FOUND: 404,
+    ErrorCode.VALIDATION_ERROR: 422,
+    ErrorCode.UNAUTHORIZED: 401,
+    ErrorCode.FORBIDDEN: 403,
+    ErrorCode.RATE_LIMITED: 429,
+    ErrorCode.CONFLICT: 409,
+    ErrorCode.INTERNAL_ERROR: 500,
+}

datagrowth_common/api/pagination.py

@@ -0,0 +1,51 @@
+"""Paginacion estandar `limit/offset`.
+
+Las queries siempre van con LIMIT (regla de rendimiento §3 del proyecto).
+Este modulo expone `paginate_params` para validar/clip de query params y
+`Paginated[T]` como envolvente de respuesta.
+"""
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+DEFAULT_LIMIT = 20
+MAX_LIMIT = 100
+
+
+class PageMeta(BaseModel):
+    total: int = Field(ge=0)
+    limit: int = Field(ge=1, le=MAX_LIMIT)
+    offset: int = Field(ge=0)
+    has_more: bool
+
+
+class Paginated(BaseModel, Generic[T]):
+    data: list[T]
+    meta: PageMeta
+
+
+def paginate_params(
+    limit: int | None = None,
+    offset: int | None = None,
+) -> tuple[int, int]:
+    """Valida y clipea limit/offset. Devuelve `(limit_safe, offset_safe)`.
+
+    `None` se trata como "no especificado" → default. Cualquier entero
+    fuera de rango se clipea (limit a [1, MAX_LIMIT], offset a [0, ∞)).
+    """
+    raw_limit = DEFAULT_LIMIT if limit is None else int(limit)
+    raw_offset = 0 if offset is None else int(offset)
+    safe_limit = max(1, min(raw_limit, MAX_LIMIT))
+    safe_offset = max(0, raw_offset)
+    return safe_limit, safe_offset
+
+
+def build_meta(total: int, limit: int, offset: int) -> PageMeta:
+    return PageMeta(
+        total=total, limit=limit, offset=offset,
+        has_more=offset + limit < total,
+    )

datagrowth_common/api/users.py

@@ -0,0 +1,78 @@
+"""Router CRUD de usuarios sobre Supabase Admin API.
+
+Para usar: `app.include_router(users_router)`. La app debe definir las
+variables de entorno `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY` y
+`SUPABASE_JWT_SECRET`.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel, EmailStr, Field
+
+from ..auth.supabase import (
+    SupabaseUser,
+    SupabaseUserDep,
+    require_role,
+)
+from ..auth import supabase_admin
+from ..api.pagination import Paginated, paginate_params
+from .errors import (
+    ApiResponse,
+    ErrorCode,
+    err_response,
+    ok_response,
+)
+
+
+users_router = APIRouter(prefix="/api/users", tags=["users"])
+
+
+class InviteBody(BaseModel):
+    email: EmailStr = Field(..., max_length=254)
+    role: str = Field(default="user", min_length=1, max_length=50)
+    redirect_to: str | None = Field(default=None, max_length=2048)
+
+
+_AdminUser = Depends(require_role("admin"))
+
+
+@users_router.get("/me", response_model=ApiResponse[SupabaseUser])
+async def get_me(user: SupabaseUserDep) -> ApiResponse[SupabaseUser]:
+    return ok_response(user)
+
+
+@users_router.get("", response_model=ApiResponse[Paginated[SupabaseUser]])
+async def list_users(
+    _admin: SupabaseUser = _AdminUser,
+    limit: int | None = Query(default=None, ge=1, le=100),
+    offset: int | None = Query(default=None, ge=0),
+) -> ApiResponse[Paginated[SupabaseUser]]:
+    safe_limit, safe_offset = paginate_params(limit, offset)
+    page, exc = await supabase_admin.list_users(limit=safe_limit, offset=safe_offset)
+    if exc is not None or page is None:
+        return err_response(ErrorCode.INTERNAL_ERROR, "list-users-failed")
+    return ok_response(page)
+
+
+@users_router.post(
+    "/invite", response_model=ApiResponse[SupabaseUser], status_code=201,
+)
+async def invite_user(
+    body: InviteBody, _admin: SupabaseUser = _AdminUser,
+) -> ApiResponse[SupabaseUser]:
+    user, exc = await supabase_admin.invite_user_by_email(
+        body.email, role=body.role, redirect_to=body.redirect_to,
+    )
+    if exc is not None or user is None:
+        return err_response(ErrorCode.INTERNAL_ERROR, "invite-failed")
+    return ok_response(user)
+
+
+@users_router.delete("/{user_id}", response_model=ApiResponse[dict])
+async def delete_user(
+    user_id: str, _admin: SupabaseUser = _AdminUser,
+) -> ApiResponse[dict]:
+    _, exc = await supabase_admin.delete_user(user_id)
+    if exc is not None:
+        return err_response(ErrorCode.INTERNAL_ERROR, "delete-failed")
+    return ok_response({"deleted": user_id})

datagrowth_common/auth/__init__.py

@@ -0,0 +1,17 @@
+"""Helpers de autenticacion para apps Datagrowth (Supabase Auth).
+
+- `supabase`: validacion de JWT firmado por Supabase Auth.
+- `supabase_admin`: wrappers async sobre Supabase Admin API (list/invite/delete users).
+- `session`: cookie httpOnly server-rendered (`set_session`, `clear_session`,
+  `require_session`, `refresh_session_tokens`). Usar en apps Jinja+HTMX.
+- `router`: `make_auth_router()` / `auth_router` con endpoints de login propio +
+  OAuth + refresh + logout, reutilizable entre el backend interno y las apps cliente.
+- `session_hmac`: cookie de sesion firmada con HMAC propio. Solo para apps
+  internas que NO usan Supabase Auth (fallback). En v0.2.x se llamaba `local`.
+
+`local` se mantiene como alias deprecated de `session_hmac` (DeprecationWarning).
+Eliminado en v0.4.0.
+"""
+from . import router, session, session_hmac, supabase, supabase_admin
+
+__all__ = ["router", "session", "session_hmac", "supabase", "supabase_admin"]

datagrowth_common/auth/local.py

@@ -0,0 +1,48 @@
+"""DEPRECATED alias: `datagrowth_common.auth.local` → `auth.session_hmac`.
+
+En v0.3.0 el archivo se renombró a `session_hmac.py` y se eliminó toda la
+integración con Authentik (OIDC, magic link, password reset, register).
+Solo se conserva la cookie HMAC de sesión propia.
+
+Importar desde aquí emite `DeprecationWarning`. Se eliminará en v0.4.0.
+"""
+from __future__ import annotations
+
+import warnings
+
+warnings.warn(
+    "datagrowth_common.auth.local is deprecated since v0.3.0; "
+    "use datagrowth_common.auth.session_hmac instead. "
+    "Authentik OIDC helpers (password_login, refresh_token, userinfo, "
+    "start_oidc, oidc_callback, register_local, magic_link_request, "
+    "password_reset, TokenPair, OidcStart) were removed; use "
+    "datagrowth_common.auth.router + datagrowth_common.auth.supabase.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from .session_hmac import (  # noqa: E402,F401
+    SessionCookie,
+    SessionDep,
+    SessionUser,
+    clear_session_cookie,
+    decode_session,
+    encode_session,
+    make_session,
+    require_group,
+    require_session,
+    set_session_cookie,
+)
+
+__all__ = [
+    "SessionCookie",
+    "SessionDep",
+    "SessionUser",
+    "clear_session_cookie",
+    "decode_session",
+    "encode_session",
+    "make_session",
+    "require_group",
+    "require_session",
+    "set_session_cookie",
+]

datagrowth_common/auth/router.py

@@ -0,0 +1,253 @@
+"""Router de autenticacion reutilizable: login propio + OAuth + refresh + logout.
+
+La pagina HTML de `/login` la sirve la propia app (cada una con su branding);
+este router solo expone los endpoints API y el OAuth callback.
+
+Uso (en `src/main.py` de la app):
+
+    from fastapi.templating import Jinja2Templates
+    from datagrowth_common.auth.router import make_auth_router
+
+    auth_router = make_auth_router(post_login_redirect="/")
+    app.include_router(auth_router)
+
+Endpoints expuestos:
+    POST /auth/password                  -> form email+password, set cookie
+    POST /auth/register                  -> sign-up (si AUTH_REGISTRATION=open)
+    POST /auth/magic-link/request        -> sign_in_with_otp(email)
+    POST /auth/password/reset            -> reset_password_for_email
+    GET  /auth/oauth/{provider}/start    -> redirige a Supabase OAuth
+    GET  /auth/oauth/{provider}/callback -> exchange code -> set cookie
+    POST /auth/refresh                   -> refresca tokens si la cookie caduco
+    POST /logout                         -> borra cookie y redirige
+    GET  /api/me                         -> SupabaseUser actual (json)
+
+Requiere las envvars:
+    SUPABASE_URL, SUPABASE_KEY, SUPABASE_JWT_SECRET (+ optional AUTH_*).
+"""
+from __future__ import annotations
+
+import os
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Form, Query, Request, Response, status
+from fastapi.responses import RedirectResponse
+from pydantic import BaseModel, EmailStr, Field
+
+from ..api.errors import (
+    ApiResponse,
+    ErrorCode,
+    err_response,
+    ok_response,
+)
+from .session import (
+    SessionUserDep,
+    clear_session,
+    get_session_tokens,
+    refresh_session_tokens,
+    set_session,
+)
+from .supabase import SupabaseUser
+
+
+def _registration_open() -> bool:
+    return os.getenv("AUTH_REGISTRATION", "invite_only") == "open"
+
+
+def _magic_link_enabled() -> bool:
+    return os.getenv("AUTH_MAGIC_LINK", "false").lower() == "true"
+
+
+def _redirect_base() -> str:
+    """URL publica de la app, para construir redirect_to del OAuth callback."""
+    return os.getenv("DG_APP_URL", "").rstrip("/")
+
+
+def _session_from_supabase(result: Any) -> dict[str, Any]:
+    session = getattr(result, "session", None)
+    if session is None:
+        return {}
+    return {
+        "access_token": getattr(session, "access_token", ""),
+        "refresh_token": getattr(session, "refresh_token", ""),
+    }
+
+
+class _RefreshBody(BaseModel):
+    pass  # refresh lee de cookie, no de body
+
+
+def make_auth_router(
+    *,
+    prefix: str = "",
+    post_login_redirect: str = "/",
+    post_logout_redirect: str = "/login",
+    oauth_callback_path_prefix: str = "/auth/oauth",
+) -> APIRouter:
+    """Construye el APIRouter de auth con redirects configurables.
+
+    El router NO sirve `/login` HTML — eso vive en la app (template propio).
+    """
+    router = APIRouter(prefix=prefix, tags=["auth"])
+
+    # ── Password (Supabase email/password) ─────────────────────────────
+
+    @router.post("/auth/password", response_class=RedirectResponse)
+    async def auth_password(
+        email: Annotated[str, Form(min_length=3, max_length=254)],
+        password: Annotated[str, Form(min_length=8, max_length=200)],
+    ) -> RedirectResponse:
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            result = client.auth.sign_in_with_password(
+                {"email": email, "password": password},
+            )
+        except Exception:
+            return RedirectResponse("/login?error=invalid-credentials", status_code=303)
+        tokens = _session_from_supabase(result)
+        if not tokens.get("access_token"):
+            return RedirectResponse("/login?error=invalid-credentials", status_code=303)
+        redir = RedirectResponse(post_login_redirect, status_code=303)
+        set_session(
+            redir,
+            access_token=tokens["access_token"],
+            refresh_token=tokens.get("refresh_token"),
+        )
+        return redir
+
+    # ── Register (sign-up) ────────────────────────────────────────────
+
+    @router.post("/auth/register", response_model=ApiResponse)
+    async def auth_register(
+        email: Annotated[str, Form(min_length=3, max_length=254)],
+        password: Annotated[str, Form(min_length=8, max_length=200)],
+        name: Annotated[str, Form(min_length=1, max_length=120)] = "",
+    ) -> ApiResponse:
+        if not _registration_open():
+            return err_response(ErrorCode.FORBIDDEN, "registration-closed")
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            client.auth.sign_up({
+                "email": email, "password": password,
+                "options": {"data": {"name": name}} if name else {},
+            })
+        except Exception:
+            return err_response(ErrorCode.CONFLICT, "register-failed")
+        return ok_response({"created": True, "email": email})
+
+    # ── Magic link (OTP via email) ────────────────────────────────────
+
+    @router.post("/auth/magic-link/request", response_model=ApiResponse)
+    async def auth_magic_link(
+        email: Annotated[str, Form(min_length=3, max_length=254)],
+    ) -> ApiResponse:
+        if not _magic_link_enabled():
+            return err_response(ErrorCode.FORBIDDEN, "magic-link-disabled")
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            client.auth.sign_in_with_otp({"email": email})
+        except Exception:
+            return err_response(ErrorCode.INTERNAL_ERROR, "magic-link-failed")
+        return ok_response({"sent": True})
+
+    # ── Password reset ────────────────────────────────────────────────
+
+    @router.post("/auth/password/reset", response_model=ApiResponse)
+    async def auth_password_reset(
+        email: Annotated[str, Form(min_length=3, max_length=254)],
+    ) -> ApiResponse:
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            client.auth.reset_password_for_email(email)
+        except Exception:
+            return err_response(ErrorCode.INTERNAL_ERROR, "reset-failed")
+        return ok_response({"sent": True})
+
+    # ── OAuth (Microsoft/Google/etc. via Supabase) ───────────────────
+
+    @router.get(f"{oauth_callback_path_prefix}/{{provider}}/start")
+    async def auth_oauth_start(
+        provider: str, request: Request,
+    ) -> RedirectResponse:
+        """Redirige al consent de Supabase para el provider OAuth indicado."""
+        base = _redirect_base() or str(request.base_url).rstrip("/")
+        callback = f"{base}{oauth_callback_path_prefix}/{provider}/callback"
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            result = client.auth.sign_in_with_oauth({
+                "provider": provider,
+                "options": {"redirect_to": callback},
+            })
+            url = getattr(result, "url", None)
+        except Exception:
+            return RedirectResponse(url="/login?error=oauth-start", status_code=303)
+        if not url:
+            return RedirectResponse(url="/login?error=oauth-start", status_code=303)
+        return RedirectResponse(url=str(url), status_code=303)
+
+    @router.get(f"{oauth_callback_path_prefix}/{{provider}}/callback")
+    async def auth_oauth_callback(
+        provider: str,
+        code: Annotated[str, Query(min_length=1, max_length=2048)],
+    ) -> RedirectResponse:
+        """Canjea el `?code=` por session JWT y guarda cookies."""
+        try:
+            from ..supabase import get_supabase_client
+            client = get_supabase_client()
+            result = client.auth.exchange_code_for_session({"auth_code": code})
+        except Exception:
+            return RedirectResponse(url="/login?error=oauth-exchange", status_code=303)
+        tokens = _session_from_supabase(result)
+        if not tokens.get("access_token"):
+            return RedirectResponse(url="/login?error=oauth-exchange", status_code=303)
+        redir = RedirectResponse(post_login_redirect, status_code=303)
+        set_session(
+            redir,
+            access_token=tokens["access_token"],
+            refresh_token=tokens.get("refresh_token"),
+        )
+        return redir
+
+    # ── Refresh ───────────────────────────────────────────────────────
+
+    @router.post("/auth/refresh", response_model=ApiResponse)
+    async def auth_refresh(
+        request: Request, response: Response,
+    ) -> ApiResponse:
+        tokens = get_session_tokens(request)
+        if tokens is None or not tokens.refresh_token:
+            return err_response(ErrorCode.UNAUTHORIZED, "no-refresh-token")
+        new_tokens, exc = await refresh_session_tokens(tokens.refresh_token)
+        if exc is not None or new_tokens is None:
+            return err_response(ErrorCode.UNAUTHORIZED, "refresh-failed")
+        set_session(
+            response,
+            access_token=new_tokens["access_token"],
+            refresh_token=new_tokens.get("refresh_token"),
+        )
+        return ok_response({"refreshed": True})
+
+    # ── Logout ────────────────────────────────────────────────────────
+
+    @router.post("/logout", response_class=RedirectResponse)
+    async def logout() -> RedirectResponse:
+        redir = RedirectResponse(post_logout_redirect, status_code=303)
+        clear_session(redir)
+        return redir
+
+    # ── Identity ──────────────────────────────────────────────────────
+
+    @router.get("/api/me", response_model=ApiResponse[SupabaseUser])
+    async def me(user: SessionUserDep) -> ApiResponse[SupabaseUser]:
+        return ok_response(user)
+
+    return router
+
+
+# Router por defecto con redirects estandar (post_login → "/").
+auth_router = make_auth_router()