simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/pages/PublicPage.tsx

@@ -0,0 +1,126 @@
+import { Head, usePage } from '@inertiajs/react';
+import { type Data, Render } from '@puckeditor/core';
+import { BrandingHead } from '@simple-module-py/ui/components/BrandingHead';
+import type { SharedProps } from '@simple-module-py/ui/types';
+
+import { getLayoutPuckConfig } from '../components/layoutPuckConfig';
+import { migrateContent } from '../components/migrateContent';
+import { getPuckConfig } from '../components/puckConfig';
+
+interface Props {
+  title: string;
+  data: Record<string, unknown>;
+  meta_description: string | null;
+  og_image: string | null;
+  canonical_url?: string | null;
+  og_url?: string | null;
+  index_in_search?: boolean;
+  json_ld?: Record<string, unknown> | null;
+  site_name?: string | null;
+  twitter_handle?: string | null;
+  layout_header?: Record<string, unknown> | null;
+  layout_footer?: Record<string, unknown> | null;
+}
+
+// Inline JSON-LD as a string requires the document to be safe to embed
+// inside ``<script>...</script>``. ``JSON.stringify`` does not escape
+// the literal sequence ``</`` (or HTML comment openers), so a value like
+// ``"</script><script>alert(1)</script>"`` would break out. The replace
+// runs over keys and string values alike; ``<\/`` parses identically to
+// ``</`` in JSON, so the document round-trips through any consumer.
+function safeJsonLd(doc: Record<string, unknown>): string {
+  return JSON.stringify(doc)
+    .replace(/<\/(script)/gi, '<\\/$1')
+    .replace(/<!--/g, '<\\!--');
+}
+
+export default function PublicPage({
+  title,
+  data,
+  meta_description,
+  og_image,
+  canonical_url,
+  og_url,
+  index_in_search = true,
+  json_ld,
+  site_name,
+  twitter_handle,
+  layout_header,
+  layout_footer,
+}: Props) {
+  const jsonLdScript = json_ld ? safeJsonLd(json_ld) : null;
+  // The design pack is a site-wide branding setting: one site, one look. Its
+  // CSS is scoped to a root class, applied here around the *whole* document so
+  // the header and footer adopt it too — a class on the page root alone would
+  // stop at <main> and leave the chrome reading as a different site.
+  //
+  // `designPack` is not on the published SharedProps type yet; the cast goes
+  // away when the framework release carrying it lands.
+  const { branding } = usePage<{ props: SharedProps }>().props as unknown as SharedProps;
+  const designPack = (branding as unknown as { designPack?: string | null })?.designPack;
+  // Bound once per render because each of the three `migrateContent` calls
+  // below needs the same config its `<Render>` gets — migrating against a
+  // different palette than the one rendering would resolve zones to slots the
+  // renderer doesn't have.
+  const pageConfig = getPuckConfig();
+  const layoutConfig = getLayoutPuckConfig();
+  return (
+    <div className={designPack ? `${designPack}-root` : undefined}>
+      {/* The admin shell mounts this through AuthenticatedLayout; a public page
+          has no layout, so without it the configured brand colour and favicon
+          stopped at the sign-in wall. The widgets' `--pb-accent` and their
+          solid `bg-primary-800` surfaces read the `--primary` / ramp variables
+          it writes, so this is what makes Settings → Branding reach the
+          public site. */}
+      <BrandingHead />
+      <Head title={title}>
+        {meta_description && (
+          <>
+            <meta name="description" content={meta_description} />
+            <meta property="og:description" content={meta_description} />
+          </>
+        )}
+        <meta property="og:title" content={title} />
+        <meta property="og:type" content="website" />
+        {og_url && <meta property="og:url" content={og_url} />}
+        {site_name && <meta property="og:site_name" content={site_name} />}
+        {og_image && (
+          <>
+            <meta property="og:image" content={og_image} />
+            <meta name="twitter:image" content={og_image} />
+          </>
+        )}
+        <meta name="twitter:card" content={og_image ? 'summary_large_image' : 'summary'} />
+        {twitter_handle && <meta name="twitter:site" content={twitter_handle} />}
+        {canonical_url && <link rel="canonical" href={canonical_url} />}
+        {!index_in_search && <meta name="robots" content="noindex,nofollow" />}
+        {jsonLdScript && (
+          // Emitting author-composed JSON-LD is the feature. The content is
+          // written by permission-holding editors and served under the CSP in
+          // PagebuilderSettings.public_csp.
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: author-composed JSON-LD is the feature
+          <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript }} />
+        )}
+      </Head>
+      {layout_header && (
+        <header data-testid="site-header">
+          <Render
+            config={layoutConfig}
+            data={migrateContent(layout_header as unknown as Data, layoutConfig)}
+          />
+        </header>
+      )}
+      <main>
+        <Render config={pageConfig} data={migrateContent(data as unknown as Data, pageConfig)} />
+      </main>
+      {layout_footer && (
+        <footer data-testid="site-footer">
+          <Render
+            config={layoutConfig}
+            data={migrateContent(layout_footer as unknown as Data, layoutConfig)}
+          />
+        </footer>
+      )}
+    </div>
+  );
+}

pagebuilder/permissions.py

@@ -0,0 +1,44 @@
+"""Permission constants + suggested role map for the pagebuilder module.
+
+The approval workflow carves three permissions out of what was
+previously a single admin surface:
+
+* ``pagebuilder.edit`` — draft, save, submit for review, restore.
+* ``pagebuilder.publish`` — publish / unpublish directly.
+* ``pagebuilder.approve`` — approve or reject a submitted page.
+
+Enforcement reuses ``simple_module_hosting.permissions.RequiresPermission``
+unchanged — re-exported here so endpoint code only needs one import.
+"""
+
+from __future__ import annotations
+
+from simple_module_hosting.permissions import RequiresPermission
+
+__all__ = [
+    "ALL_PERMISSIONS",
+    "DEFAULT_ROLE_MAP",
+    "PERM_APPROVE",
+    "PERM_EDIT",
+    "PERM_PUBLISH",
+    "ROLE_APPROVER",
+    "ROLE_EDITOR",
+    "ROLE_PUBLISHER",
+    "RequiresPermission",
+]
+
+PERM_EDIT = "pagebuilder.edit"
+PERM_PUBLISH = "pagebuilder.publish"
+PERM_APPROVE = "pagebuilder.approve"
+
+ALL_PERMISSIONS: tuple[str, ...] = (PERM_EDIT, PERM_PUBLISH, PERM_APPROVE)
+
+ROLE_EDITOR = "pagebuilder_editor"
+ROLE_PUBLISHER = "pagebuilder_publisher"
+ROLE_APPROVER = "pagebuilder_approver"
+
+DEFAULT_ROLE_MAP: dict[str, list[str]] = {
+    ROLE_EDITOR: [PERM_EDIT],
+    ROLE_PUBLISHER: [PERM_EDIT, PERM_PUBLISH],
+    ROLE_APPROVER: [PERM_EDIT, PERM_PUBLISH, PERM_APPROVE],
+}

pagebuilder/security.py

@@ -0,0 +1,230 @@
+"""Auth + CSRF dependencies for pagebuilder admin endpoints.
+
+The pagebuilder module historically assumed the host gated ``/pagebuilder/*``
+and ``/api/pagebuilder/*`` via session-cookie middleware. A host that
+forgets to mount auth — or one that swaps the users module out — would
+expose page CRUD + media upload to the public internet. These helpers
+move the gate inside the module so it's secure by default.
+
+The dependencies are intentionally lazy: importing ``auth.deps`` at
+module top-level would couple the pagebuilder test app to the users
+module's database schema, which we don't want in unit tests.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Annotated, Any
+
+from fastapi import Depends, HTTPException, Request
+from inertia import Inertia
+from simple_module_hosting.inertia_deps import get_inertia
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+_CSRF_SESSION_KEY = "pagebuilder_csrf_token"
+_CSRF_HEADER_NAME = "x-csrf-token"
+_UNSAFE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+async def get_current_user_or_401(request: Request) -> Any:
+    """Return the authenticated user or raise 401.
+
+    Reads ``request.state.user`` (set by the host's auth middleware).
+    We don't import ``auth.deps.get_current_user`` because it depends on
+    the i18n TranslatorDep — the failure mode we care about is "no auth
+    middleware mounted at all", which would leave ``request.state.user``
+    unset regardless of which dep we use.
+    """
+    user = getattr(request.state, "user", None)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    return user
+
+
+def _get_or_create_csrf_token(request: Request) -> str | None:
+    """Generate (and persist) the per-session CSRF token.
+
+    Returns ``None`` when the request has no session — happens in the
+    bare-FastAPI test app that doesn't mount SessionMiddleware. Callers
+    can treat ``None`` as "skip CSRF enforcement" since without a session
+    we have no anchor to bind the token to anyway.
+    """
+    session = request.scope.get("session")
+    if session is None:
+        return None
+    token = session.get(_CSRF_SESSION_KEY)
+    if not token:
+        token = secrets.token_urlsafe(32)
+        session[_CSRF_SESSION_KEY] = token
+    return token
+
+
+def get_csrf_token(request: Request) -> str:
+    """Public dep that returns the current CSRF token, generating if needed.
+
+    Returns an empty string when no session is mounted so view code can
+    pass it straight to Inertia props without a None-check.
+    """
+    return _get_or_create_csrf_token(request) or ""
+
+
+async def verify_csrf(request: Request) -> None:
+    """Enforce ``X-CSRF-Token`` header on every mutating admin request.
+
+    Skipped on safe methods (GET / HEAD / OPTIONS) and when no session is
+    mounted (test harnesses without SessionMiddleware). The header value
+    is compared in constant time against the per-session token.
+    """
+    if request.method not in _UNSAFE_METHODS:
+        return
+    session = request.scope.get("session")
+    if session is None:
+        return
+    expected = session.get(_CSRF_SESSION_KEY)
+    received = request.headers.get(_CSRF_HEADER_NAME)
+    if not expected or not received or not secrets.compare_digest(
+        str(expected), str(received)
+    ):
+        raise HTTPException(status_code=403, detail="Invalid or missing CSRF token")
+
+
+async def share_csrf_to_inertia(
+    request: Request,
+    inertia: Annotated[Inertia, Depends(get_inertia)],
+) -> None:
+    """Surface the CSRF token to the React client via shared Inertia props.
+
+    The companion :class:`CsrfCookieMiddleware` writes the same value to
+    a non-``HttpOnly`` cookie so the JS layer can read it back for
+    sub-resources that don't go through Inertia page props (notably
+    multipart media uploads, which can't easily include the token via
+    JSON props).
+
+    We share via Inertia props rather than a route-level
+    ``response.set_cookie`` because FastAPI doesn't merge a dependency's
+    cookie writes into a ``Response`` returned by the handler — and the
+    Inertia view handlers all return ``InertiaResponse`` directly.
+    """
+    settings = _get_settings(request)
+    if not settings.csrf_protect:
+        return
+    token = _get_or_create_csrf_token(request)
+    if token is None:
+        return
+    inertia.share(csrf={"token": token, "header": "X-CSRF-Token"})
+
+
+class CsrfCookieMiddleware:
+    """Mirror the session's CSRF token to a JS-readable cookie.
+
+    Lives in a middleware (not the share dep) because FastAPI doesn't
+    merge a dep's cookie writes into a ``Response`` returned by the
+    handler — Inertia views always return one, so the dep route is a
+    dead end for cookie setting.
+
+    Two short-circuits keep this off the hot path: requests outside the
+    admin prefixes (public viewer, static assets) skip the response
+    wrapper entirely, and the wrapper itself emits no ``Set-Cookie`` when
+    the request already arrived with a cookie matching the session
+    token.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        cookie_name: str,
+        admin_prefixes: tuple[str, ...] = (),
+    ) -> None:
+        self.app = app
+        self.cookie_name = cookie_name
+        self.admin_prefixes = admin_prefixes
+        self._cookie_attr = f"{cookie_name}="
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        if self.admin_prefixes and not any(
+            scope["path"].startswith(p) for p in self.admin_prefixes
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                session = scope.get("session")
+                token = (
+                    session.get(_CSRF_SESSION_KEY) if isinstance(session, dict) else None
+                )
+                if token and _request_cookie_value(scope, self._cookie_attr) != token:
+                    headers = MutableHeaders(scope=message)
+                    headers.append(
+                        "set-cookie",
+                        f"{self.cookie_name}={token}; Path=/; SameSite=Strict",
+                    )
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+
+def _request_cookie_value(scope: Scope, attr: str) -> str | None:
+    """Read the cookie value matching ``attr`` (e.g. ``"pagebuilder_csrf="``).
+
+    Hand-rolled instead of using ``starlette.requests.cookies`` to avoid
+    re-parsing the whole Cookie header for one attribute on every admin
+    request.
+    """
+    for name, value in scope.get("headers", ()):
+        if name == b"cookie":
+            for piece in value.decode("latin-1").split(";"):
+                trimmed = piece.lstrip()
+                if trimmed.startswith(attr):
+                    return trimmed[len(attr):]
+    return None
+
+
+def _get_settings(request: Request):
+    """Resolve the pagebuilder settings from app state.
+
+    Mirrors :func:`pagebuilder.deps.get_settings` but inlined to avoid an
+    import cycle: ``deps`` imports from settings, settings is fine, but
+    security depending on deps would force security to import the
+    MediaService transitively.
+    """
+    return request.app.state.pagebuilder.settings
+
+
+def build_admin_dependencies(
+    *, requires_auth: bool, csrf_protect: bool
+) -> list[Any]:
+    """Mutating-side dependencies applied to the API router.
+
+    Returned items are ``Depends(...)`` wrappers ready to be passed to
+    ``APIRouter(dependencies=...)``. The dependency order matters: auth
+    runs first so an unauthenticated request gets 401 (the more useful
+    error) before CSRF fails it with 403.
+    """
+    deps: list[Any] = []
+    if requires_auth:
+        deps.append(Depends(get_current_user_or_401))
+    if csrf_protect:
+        deps.append(Depends(verify_csrf))
+    return deps
+
+
+def build_view_dependencies(
+    *, requires_auth: bool, csrf_protect: bool
+) -> list[Any]:
+    """View-side dependencies applied to the Inertia view router.
+
+    Mirrors :func:`build_admin_dependencies` but emits the CSRF token
+    via Inertia shared-props + cookie instead of enforcing it (Inertia
+    GETs are safe methods, so verification is a no-op anyway).
+    """
+    deps: list[Any] = []
+    if requires_auth:
+        deps.append(Depends(get_current_user_or_401))
+    if csrf_protect:
+        deps.append(Depends(share_csrf_to_inertia))
+    return deps

pagebuilder/service/__init__.py

@@ -0,0 +1,141 @@
+"""Business logic for pagebuilder pages.
+
+Service is constructed per-request from the injected ``AsyncSession``;
+the DB session's commit-on-write behavior is provided by the framework's
+``get_db`` dependency.
+
+``PagesService`` is composed from two mixins so no single file carries the
+whole surface: :mod:`._workflow` holds the status transitions and
+:mod:`._revisions` the revision history. Page CRUD and queries stay here.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+from simple_module_core.events import EventBus
+from sqlalchemy import delete as sa_delete
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from pagebuilder.contracts.events import PageDeleted
+from pagebuilder.contracts.schemas import PageCreate, PageUpdate
+from pagebuilder.models import Page, PageRevision, PageStatus
+from pagebuilder.service._common import _UNSET, _normalize_to_utc
+from pagebuilder.service._revisions import RevisionsMixin
+from pagebuilder.service._workflow import WorkflowMixin
+
+# _UNSET is re-exported: endpoints import it to express "field absent".
+__all__ = ["_UNSET", "PagesService"]
+
+
+class PagesService(WorkflowMixin, RevisionsMixin):
+    def __init__(self, db: AsyncSession, event_bus: EventBus | None = None) -> None:
+        self.db = db
+        # Optional so every existing caller — and every test — keeps working;
+        # only the delete path uses it.
+        self.event_bus = event_bus
+
+    async def list_pages(self) -> list[Page]:
+        result = await self.db.execute(select(Page).order_by(Page.id.desc()))
+        return list(result.scalars().all())
+
+    async def list_pending(self) -> list[Page]:
+        """Pages in ``submitted_for_review`` — the approver queue."""
+        result = await self.db.execute(
+            select(Page)
+            .where(Page.status == PageStatus.SUBMITTED_FOR_REVIEW)
+            .order_by(Page.id.desc())
+        )
+        return list(result.scalars().all())
+
+    async def get_page(self, page_id: int) -> Page:
+        page = await self.db.get(Page, page_id)
+        if page is None:
+            raise HTTPException(status_code=404, detail="Page not found")
+        return page
+
+    async def get_by_slug_published(self, slug: str) -> Page | None:
+        result = await self.db.execute(
+            select(Page).where(
+                Page.slug == slug,
+                Page.status == PageStatus.PUBLISHED,
+            )
+        )
+        return result.scalars().first()
+
+    async def list_indexable_published(self) -> list[Page]:
+        """Published pages eligible for sitemap inclusion.
+
+        Excludes ``index_in_search=False`` (used both by the sitemap
+        generator and any external indexing job). Ordered by ``updated_at``
+        descending so the freshest content surfaces first when a consumer
+        only reads the head of the list.
+        """
+        result = await self.db.execute(
+            select(Page)
+            .where(
+                Page.status == PageStatus.PUBLISHED,
+                Page.index_in_search.is_(True),  # type: ignore[union-attr]
+            )
+            .order_by(Page.updated_at.desc())
+        )
+        return list(result.scalars().all())
+
+    async def create(self, data: PageCreate) -> Page:
+        page = Page(
+            title=data.title,
+            slug=data.slug,
+            meta_description=data.meta_description,
+            og_image=data.og_image,
+            canonical_url=data.canonical_url,
+            index_in_search=data.index_in_search,
+            json_ld=data.json_ld,
+            draft_data=data.draft_data,
+            publish_at=_normalize_to_utc(data.publish_at),
+            unpublish_at=_normalize_to_utc(data.unpublish_at),
+            status=PageStatus.DRAFT,
+        )
+        self.db.add(page)
+        try:
+            await self.db.flush()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise HTTPException(status_code=409, detail="Slug already in use") from exc
+        await self.db.refresh(page)
+        return page
+
+    async def update(self, page_id: int, data: PageUpdate) -> Page:
+        page = await self.get_page(page_id)
+        update = data.model_dump(exclude_unset=True)
+        for field, value in update.items():
+            setattr(page, field, value)
+        self.db.add(page)
+        try:
+            await self.db.flush()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise HTTPException(status_code=409, detail="Slug already in use") from exc
+        await self.db.refresh(page)
+        return page
+
+    async def delete(self, page_id: int) -> None:
+        page = await self.get_page(page_id)
+        slug = page.slug
+        await self.db.execute(
+            sa_delete(PageRevision).where(PageRevision.page_id == page_id)
+        )
+        await self.db.delete(page)
+        await self.db.flush()
+        if self.event_bus is None:
+            return
+        # Commit *before* publishing. A subscriber runs on its own session, so
+        # on SQLite it would hit "database is locked" against this request's
+        # still-open write transaction — and the bus swallows a handler error
+        # into a log line, so the row would quietly survive.
+        await self.db.commit()
+        # Announce it so modules keying their own rows to this page can drop
+        # them. Without this a stale row does not merely dangle — SQLite reuses
+        # the id, so it re-attaches to the next page created.
+        await self.event_bus.publish(PageDeleted(page_id=page_id, slug=slug))
+

pagebuilder/service/_common.py

@@ -0,0 +1,24 @@
+"""Sentinels and helpers shared by the service mixins.
+
+Lives in its own module so ``_workflow`` can import it without reaching back
+into ``pagebuilder.service``, which imports ``_workflow`` in turn.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+class _Unset:
+    """Sentinel separating ``field=None`` (clear) from "field not provided"."""
+
+
+_UNSET = _Unset()
+
+
+def _normalize_to_utc(value: datetime | None) -> datetime | None:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=UTC)
+    return value.astimezone(UTC)

pagebuilder/service/_revisions.py

@@ -0,0 +1,92 @@
+"""Revision recording, history, diffing, and restore.
+
+Mixed into :class:`~pagebuilder.service.PagesService`. Split out to keep each
+file focused; the methods are unchanged and still rely on ``self.db`` and
+``self.get_page`` from the composing class.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import select
+
+from pagebuilder.diff import revision_diff
+from pagebuilder.models import Page, PageRevision, RevisionEvent
+
+
+class RevisionsMixin:
+    """Revision behaviour for :class:`PagesService`."""
+
+    db: AsyncSession
+
+    async def get_page(self, page_id: int) -> Page:  # pragma: no cover - provided by PagesService
+        raise NotImplementedError
+
+    def _record_revision(
+        self,
+        page: Page,
+        *,
+        event: RevisionEvent,
+        note: str | None = None,
+    ) -> PageRevision:
+        """Append an audit row mirroring *page*'s current draft state.
+
+        Publish / approve callers overwrite ``published_data`` with
+        ``draft_data`` before recording, so ``draft_data`` is the single
+        snapshot source every event needs. Caller owns the flush so the
+        page row + revision land in one transaction.
+        """
+        revision = PageRevision(
+            page_id=page.id or 0,
+            title=page.title,
+            meta_description=page.meta_description,
+            og_image=page.og_image,
+            data=page.draft_data,
+            event=event,
+            note=note,
+        )
+        self.db.add(revision)
+        return revision
+
+
+    async def list_revisions(self, page_id: int) -> list[PageRevision]:
+        result = await self.db.execute(
+            select(PageRevision)
+            .where(PageRevision.page_id == page_id)
+            .order_by(PageRevision.id.desc())
+        )
+        return list(result.scalars().all())
+
+    async def get_revision(self, page_id: int, revision_id: int) -> PageRevision:
+        revision = await self.db.get(PageRevision, revision_id)
+        if revision is None or revision.page_id != page_id:
+            raise HTTPException(status_code=404, detail="Revision not found")
+        return revision
+
+    async def diff_revisions(self, page_id: int, before_id: int, after_id: int) -> dict:
+        """Block-level diff between two revisions of the same page.
+
+        Both revisions are validated to belong to ``page_id`` via
+        :meth:`get_revision`, so a cross-page id pair surfaces as a 404
+        rather than silently diffing across pages.
+        """
+        before = await self.get_revision(page_id, before_id)
+        after = await self.get_revision(page_id, after_id)
+        result = revision_diff(before, after)
+        result["before_id"] = before.id
+        result["after_id"] = after.id
+        return result
+
+    async def restore_revision(self, page_id: int, revision_id: int) -> Page:
+        """Copy a revision's payload into the page's draft (does not publish)."""
+        page = await self.get_page(page_id)
+        revision = await self.get_revision(page_id, revision_id)
+        page.title = revision.title
+        page.meta_description = revision.meta_description
+        page.og_image = revision.og_image
+        page.draft_data = revision.data
+        self.db.add(page)
+        await self.db.flush()
+        await self.db.refresh(page)
+        return page