supython 0.5.0__py3-none-any.whl

supython/__init__.py

@@ -0,0 +1,8 @@
+"""supython: a lightweight Postgres-first BaaS framework for Python."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("supython")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

supython/admin/__init__.py

@@ -0,0 +1,3 @@
+from .api import router
+
+__all__ = ["router"]

supython/admin/api/__init__.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter
+
+from .auth import router as auth_router
+from .auth_templates import router as auth_templates_router
+from .auth_users import router as auth_users_router
+from .db import router as db_router
+from .functions import router as functions_router
+from .jobs import router as jobs_router
+from .ops import router as ops_router
+from .realtime import router as realtime_router
+from .storage import router as storage_router
+from .system import router as system_router
+
+router = APIRouter()
+router.include_router(auth_router)
+router.include_router(auth_templates_router)
+router.include_router(auth_users_router)
+router.include_router(system_router)
+router.include_router(db_router)
+router.include_router(storage_router)
+router.include_router(functions_router)
+router.include_router(jobs_router)
+router.include_router(realtime_router)
+router.include_router(ops_router)

supython/admin/api/auth.py

@@ -0,0 +1,118 @@
+import ipaddress
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Cookie, Depends, HTTPException, Request, Response, status
+
+from ... import db
+from .. import audit
+from .. import session as admin_session
+from ..errors import AdminError, to_http
+from ..schemas import LoginRequest, SessionResponse
+from . import service_auth
+
+router = APIRouter(prefix="/admin/api/v1/auth", tags=["admin.auth"])
+
+
+def _client_ip(request: Request) -> str | None:
+    if request.client is None:
+        return None
+    try:
+        ipaddress.ip_address(request.client.host)
+    except ValueError:
+        return None
+    return request.client.host
+
+
+@router.post("/login", response_model=SessionResponse)
+async def login(
+    payload: LoginRequest, request: Request, response: Response
+) -> SessionResponse:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            admin_id, email = await service_auth.authenticate(
+                conn, payload.email, payload.password
+            )
+            token, expires = await admin_session.issue(
+                conn, admin_id=admin_id, ip=ip, ua=ua
+            )
+            await service_auth.touch_last_login(conn, admin_id)
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="admin.login",
+                target=payload.email,
+                payload={"email": payload.email},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        async with db.as_service_role() as audit_conn:
+            await audit.write(
+                audit_conn,
+                admin_id=None,
+                action="admin.login.failed",
+                target=payload.email,
+                payload={"email": payload.email, "error_code": exc.code},
+                ip=ip,
+                ua=ua,
+            )
+        raise to_http(exc) from exc
+    response.set_cookie(
+        admin_session.SESSION_COOKIE,
+        token,
+        max_age=int(admin_session.SESSION_TTL.total_seconds()),
+        httponly=True,
+        secure=True,
+        samesite="strict",
+        path=admin_session.SESSION_PATH,
+    )
+    return SessionResponse(admin_id=admin_id, email=email, expires_at=expires)
+
+
+@router.post("/logout", status_code=204)
+async def logout(
+    request: Request,
+    response: Response,
+    cookie: Annotated[str | None, Cookie(alias=admin_session.SESSION_COOKIE)] = None,
+) -> None:
+    if cookie:
+        ip = _client_ip(request)
+        ua = request.headers.get("user-agent")
+        async with db.as_service_role() as conn:
+            resolved = await admin_session.resolve(conn, cookie)
+            if resolved is not None:
+                admin_id, _expires = resolved
+                await audit.write(
+                    conn,
+                    admin_id=admin_id,
+                    action="admin.logout",
+                    target=None,
+                    payload={},
+                    ip=ip,
+                    ua=ua,
+                )
+            await admin_session.revoke(conn, cookie)
+    response.delete_cookie(admin_session.SESSION_COOKIE, path=admin_session.SESSION_PATH)
+
+
+@router.get("/session", response_model=SessionResponse)
+async def session(
+    request: Request,
+    cookie: Annotated[str | None, Cookie(alias=admin_session.SESSION_COOKIE)] = None,
+) -> SessionResponse:
+    if not cookie:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Admin session required")
+    async with db.as_service_role() as conn:
+        resolved = await admin_session.resolve(conn, cookie)
+        if resolved is None:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid or expired session")
+        admin_id, expires = resolved
+        info = await service_auth.fetch_admin(conn, admin_id)
+    if info is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Admin user not found")
+    email, _last_login = info
+    request.state.admin_id = admin_id
+    return SessionResponse(admin_id=admin_id, email=email, expires_at=expires)

supython/admin/api/auth_templates.py

@@ -0,0 +1,67 @@
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Request
+
+from ... import db
+from .. import audit
+from ..deps import require_admin
+from ..errors import AdminError, to_http
+from ..schemas import EmailTemplate, EmailTemplateUpdate
+from . import service_auth_templates
+
+router = APIRouter(prefix="/admin/api/v1/auth", tags=["admin.auth.templates"])
+
+
+@router.get("/templates", response_model=list[EmailTemplate])
+async def list_templates(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[EmailTemplate]:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_templates.list_templates(conn)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/templates/{name}", response_model=EmailTemplate)
+async def get_template(
+    name: str,
+    _: Annotated[UUID, Depends(require_admin)],
+) -> EmailTemplate:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_templates.get_template(conn, name)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.patch("/templates/{name}", response_model=EmailTemplate)
+async def update_template(
+    name: str,
+    payload: EmailTemplateUpdate,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+) -> EmailTemplate:
+    try:
+        async with db.as_service_role() as conn:
+            result = await service_auth_templates.update_template(
+                conn,
+                name,
+                payload.subject,
+                payload.text_body,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+    async with db.as_service_role() as conn:
+        await audit.write(
+            conn,
+            admin_id=admin_id,
+            action="auth.template.update",
+            target=name,
+            payload=payload.model_dump(exclude_none=True),
+            ip=request.client.host if request.client else None,
+            ua=request.headers.get("user-agent"),
+        )
+    return result

supython/admin/api/auth_users.py

@@ -0,0 +1,225 @@
+import ipaddress
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, Request
+
+from ... import db
+from .. import audit
+from ..deps import require_admin
+from ..errors import AdminError, to_http
+from ..schemas import (
+    AdminAuditPage,
+    AdminUserDetail,
+    AdminUsersPage,
+    BanRequest,
+    RefreshTokensPage,
+)
+from . import service_auth_users
+
+router = APIRouter(prefix="/admin/api/v1/auth", tags=["admin.auth.users"])
+
+
+def _client_ip(request: Request) -> str | None:
+    if request.client is None:
+        return None
+    try:
+        ipaddress.ip_address(request.client.host)
+    except ValueError:
+        return None
+    return request.client.host
+
+
+@router.get("/users", response_model=AdminUsersPage)
+async def list_users(
+    _: Annotated[UUID, Depends(require_admin)],
+    search: str | None = None,
+    confirmed: bool | None = None,
+    banned: bool | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> AdminUsersPage:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_users.search_users(
+                conn, search, confirmed, banned, limit, offset
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/users/{user_id}", response_model=AdminUserDetail)
+async def get_user(
+    user_id: UUID,
+    _: Annotated[UUID, Depends(require_admin)],
+) -> AdminUserDetail:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_users.get_user_detail(conn, user_id)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.post("/users/{user_id}/ban")
+async def ban_user(
+    user_id: UUID,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+    payload: Annotated[BanRequest | None, Body()] = None,
+) -> dict[str, str]:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    duration = payload.duration_seconds if payload else None
+    try:
+        async with db.as_service_role() as conn:
+            banned_until = await service_auth_users.ban_user(conn, user_id, duration)
+            await service_auth_users.write_user_audit(
+                conn,
+                user_id=user_id,
+                event="user.banned",
+                payload={"banned_until": banned_until.isoformat()},
+                ip=ip,
+                ua=ua,
+            )
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="auth.user.ban",
+                target=str(user_id),
+                payload={"banned_until": banned_until.isoformat()},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+    return {"banned_until": banned_until.isoformat()}
+
+
+@router.post("/users/{user_id}/unban", status_code=204)
+async def unban_user(
+    user_id: UUID,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+) -> None:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            await service_auth_users.unban_user(conn, user_id)
+            await service_auth_users.write_user_audit(
+                conn,
+                user_id=user_id,
+                event="user.unbanned",
+                payload={},
+                ip=ip,
+                ua=ua,
+            )
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="auth.user.unban",
+                target=str(user_id),
+                payload={},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.post("/users/{user_id}/force-logout")
+async def force_logout(
+    user_id: UUID,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+) -> dict[str, int]:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            revoked = await service_auth_users.force_logout(conn, user_id)
+            await service_auth_users.write_user_audit(
+                conn,
+                user_id=user_id,
+                event="user.force_logout",
+                payload={"revoked": revoked},
+                ip=ip,
+                ua=ua,
+            )
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="auth.user.force_logout",
+                target=str(user_id),
+                payload={"revoked": revoked},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+    return {"revoked": revoked}
+
+
+@router.get("/refresh-tokens", response_model=RefreshTokensPage)
+async def list_refresh_tokens(
+    _: Annotated[UUID, Depends(require_admin)],
+    user_id: UUID | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> RefreshTokensPage:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_users.list_refresh_tokens(conn, user_id, limit, offset)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.delete("/refresh-tokens/{token_id}", status_code=204)
+async def revoke_refresh_token(
+    token_id: int,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+) -> None:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            user_id = await service_auth_users.revoke_refresh_token(conn, token_id)
+            await service_auth_users.write_user_audit(
+                conn,
+                user_id=user_id,
+                event="refresh_token.revoked",
+                payload={"token_id": token_id},
+                ip=ip,
+                ua=ua,
+            )
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="auth.refresh_token.revoke",
+                target=str(token_id),
+                payload={"token_id": token_id, "user_id": str(user_id)},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/audit", response_model=AdminAuditPage)
+async def list_audit(
+    _: Annotated[UUID, Depends(require_admin)],
+    event: str | None = None,
+    ip: str | None = None,
+    from_date: str | None = None,
+    to_date: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> AdminAuditPage:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_auth_users.list_audit_log(
+                conn, event, ip, from_date, to_date, limit, offset
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc

supython/admin/api/db.py

@@ -0,0 +1,174 @@
+import ipaddress
+from typing import Annotated, Literal
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, Request
+
+from ... import db
+from .. import audit
+from ..deps import require_admin
+from ..errors import AdminError, to_http
+from ..schemas import (
+    DryRunRequest,
+    DryRunResponse,
+    MigrationRecord,
+    RlsPolicy,
+    RowsPage,
+    SchemaInfo,
+    SqlExecRequest,
+    SqlExecResponse,
+    TableInfo,
+)
+from . import service_db
+
+router = APIRouter(prefix="/admin/api/v1/db", tags=["admin.db"])
+
+
+def _client_ip(request: Request) -> str | None:
+    if request.client is None:
+        return None
+    try:
+        ipaddress.ip_address(request.client.host)
+    except ValueError:
+        return None
+    return request.client.host
+
+
+@router.get("/schemas", response_model=list[SchemaInfo])
+async def list_schemas(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[SchemaInfo]:
+    async with db.as_service_role() as conn:
+        return await service_db.list_schemas(conn)
+
+
+@router.get("/tables/{schema}", response_model=list[TableInfo])
+async def list_tables(
+    schema: str,
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[TableInfo]:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_db.list_tables(conn, schema)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/tables/{schema}/{table}/rows", response_model=RowsPage)
+async def read_rows(
+    schema: str,
+    table: str,
+    _: Annotated[UUID, Depends(require_admin)],
+    limit: int = 50,
+    offset: int = 0,
+    order: str | None = None,
+    role: Literal["service_role", "authenticated", "anon"] = "service_role",
+    impersonate_sub: UUID | None = None,
+) -> RowsPage:
+    try:
+        if role == "service_role":
+            async with db.as_service_role() as conn:
+                return await service_db.read_rows(conn, schema, table, limit, offset, order)
+        claims = service_db.preview_claims(role, impersonate_sub)
+        async with db.as_role(role, claims) as conn:
+            return await service_db.read_rows(conn, schema, table, limit, offset, order)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.post("/sql/execute", response_model=SqlExecResponse)
+async def run_sql(
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+    payload: Annotated[SqlExecRequest, Body()],
+) -> SqlExecResponse:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            try:
+                result = await service_db.execute_sql(conn, payload)
+            except AdminError as exc:
+                # Audit the failed attempt on a fresh connection so the poisoned
+                # transaction is not reused.
+                async with db.as_service_role() as audit_conn:
+                    await audit.write(
+                        audit_conn,
+                        admin_id=admin_id,
+                        action="sql.execute.failed",
+                        target=None,
+                        payload={
+                            "statement": payload.statement[:2048],
+                            "error_code": exc.code,
+                        },
+                        ip=ip,
+                        ua=ua,
+                    )
+                raise
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="sql.execute",
+                target=None,
+                payload={
+                    "statement": payload.statement[:2048],
+                    "row_count": result.row_count,
+                },
+                ip=ip,
+                ua=ua,
+            )
+        return result
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/rls/{schema}/{table}", response_model=list[RlsPolicy])
+async def list_policies(
+    schema: str,
+    table: str,
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[RlsPolicy]:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_db.list_policies(conn, schema, table)
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.post("/rls/dry-run", response_model=DryRunResponse)
+async def dry_run_policy(
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+    payload: Annotated[DryRunRequest, Body()],
+) -> DryRunResponse:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        async with db.as_service_role() as conn:
+            result = await service_db.dry_run_policy(conn, payload.ddl, payload.sample_query)
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="rls.dry_run",
+                target=None,
+                payload={
+                    "ddl": payload.ddl[:2048],
+                    "sample_query": payload.sample_query[:2048],
+                },
+                ip=ip,
+                ua=ua,
+            )
+            return result
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.get("/migrations", response_model=list[MigrationRecord])
+async def list_migrations(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[MigrationRecord]:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_db.list_migrations(conn)
+    except AdminError as exc:
+        raise to_http(exc) from exc