sardine-cms-admin 0.1.0__py3-none-any.whl

cms_admin/__init__.py

@@ -0,0 +1,6 @@
+"""Sardine CMS admin panel (ADR-0013): FastAPI API + server-rendered UI."""
+
+from cms_admin.app import create_app
+from cms_admin.settings import AdminSettings
+
+__all__ = ["AdminSettings", "create_app"]

cms_admin/app.py

@@ -0,0 +1,102 @@
+"""Application factory.
+
+One FastAPI process serves the API and the server-rendered UI (ADR-0013).
+Storage is opened once per process (any supported engine, via the
+thread-affine ``StorageExecutor``) and closed on shutdown; handlers reach it
+through ``get_db``.
+"""
+
+import tempfile
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from cms_admin.articles import router as articles_router
+from cms_admin.auth import get_db
+from cms_admin.auth import router as auth_router
+from cms_admin.dashboard import router as dashboard_router
+from cms_admin.db import StorageExecutor
+from cms_admin.media import router as media_router
+from cms_admin.pages import router as pages_router
+from cms_admin.publishing import router as publishing_router
+from cms_admin.settings import AdminSettings
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
+    settings: AdminSettings = app.state.settings
+    app.state.db = StorageExecutor(settings.storage_url)
+    try:
+        yield
+    finally:
+        app.state.db.close()
+
+
+# Hardening (SECURITY_STRATEGY, M3 phase 9): the admin ships zero JavaScript,
+# so the CSP allows no script source at all; styles, fonts and images come
+# only from the app itself; nothing may frame it.
+SECURITY_HEADERS = {
+    "Content-Security-Policy": (
+        "default-src 'none'; style-src 'self'; font-src 'self'; "
+        "img-src 'self' data:; form-action 'self'; base-uri 'none'; "
+        "frame-ancestors 'none'"
+    ),
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Permissions-Policy": "geolocation=(), microphone=(), camera=()",
+}
+
+
+def create_app(settings: AdminSettings | None = None) -> FastAPI:
+    from cms_admin.auth import LoginRateLimiter
+
+    app = FastAPI(title="Sardine CMS admin", lifespan=_lifespan, docs_url=None, redoc_url=None)
+
+    @app.middleware("http")
+    async def _security_headers(request: Request, call_next):  # type: ignore[no-untyped-def]
+        response = await call_next(request)
+        for name, value in SECURITY_HEADERS.items():
+            response.headers.setdefault(name, value)
+        return response
+
+    app.state.settings = settings if settings is not None else AdminSettings.from_env()
+    # autoescape must be forced on: the stock select_autoescape does not
+    # recognize the .html.j2 extension and would render templates unescaped.
+    app.state.templates = Jinja2Templates(
+        env=Environment(
+            loader=FileSystemLoader(Path(__file__).parent / "templates"),
+            autoescape=select_autoescape(default=True, default_for_string=True),
+        )
+    )
+    app.state.login_limiter = LoginRateLimiter()
+    app.include_router(auth_router)
+    app.include_router(dashboard_router)
+    app.include_router(articles_router)
+    app.include_router(pages_router)
+    app.include_router(media_router)
+    app.include_router(publishing_router)
+    app.state.preview_dir = tempfile.mkdtemp(prefix="sardine-preview-")
+    app.mount("/static", StaticFiles(directory=Path(__file__).parent / "static"), name="static")
+    app.mount(
+        "/preview",
+        StaticFiles(directory=app.state.preview_dir, html=True, check_dir=False),
+        name="preview",
+    )
+    app.mount(
+        "/media-files",
+        StaticFiles(directory=app.state.settings.media_dir, check_dir=False),
+        name="media-files",
+    )
+
+    @app.get("/healthz")
+    async def healthz(request: Request) -> dict[str, str | int]:
+        version = await get_db(request).run(lambda storage: storage.schema_version())
+        return {"status": "ok", "schema_version": version}
+
+    return app

cms_admin/articles.py

@@ -0,0 +1,393 @@
+"""Articles: list, create, and the side-by-side translation editor.
+
+The EN source is edited on the article page; each translation is edited next
+to a read-only view of the source it translates (the checksum model marks it
+outdated automatically when the source changes afterwards). The preview uses
+the builder's own Markdown renderer, so what an editor sees is exactly what
+the published site will render — raw HTML stays disabled.
+"""
+
+from datetime import UTC, datetime
+
+from cms_build import render_markdown
+from cms_core import (
+    AdminSession,
+    Article,
+    ArticleContent,
+    ContentStatus,
+    Language,
+    Role,
+    User,
+    new_article,
+)
+from cms_core.languages import SOURCE_LANGUAGE, TARGET_LANGUAGES
+from cms_validation import SiteContent
+from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
+from fastapi.responses import RedirectResponse
+from pydantic import ValidationError
+
+from cms_admin.auth import current_session, enforce_csrf, get_db
+from cms_admin.workflow import (
+    allowed,
+    available_transitions,
+    publish_blockers,
+    transition_minimum,
+)
+
+router = APIRouter(prefix="/articles")
+
+HTTP_422 = status.HTTP_422_UNPROCESSABLE_CONTENT
+
+
+def form_errors(error: ValidationError) -> list[str]:
+    return [
+        f"{'.'.join(str(part) for part in item['loc']) or 'form'}: {item['msg']}"
+        for item in error.errors()
+    ]
+
+
+def parse_tags(raw: str) -> tuple[str, ...]:
+    return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+def content_form(content: ArticleContent | None) -> dict[str, str]:
+    if content is None:
+        return {"title": "", "summary": "", "body_markdown": "", "slug": ""}
+    return {
+        "title": content.title,
+        "summary": content.summary,
+        "body_markdown": content.body_markdown,
+        "slug": content.slug or "",
+    }
+
+
+def _target_language(code: str) -> Language:
+    try:
+        language = Language(code)
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="unknown language"
+        ) from None
+    if language is SOURCE_LANGUAGE:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="the source language is edited on the article page",
+        )
+    return language
+
+
+async def _load_article(request: Request, article_id: str) -> Article:
+    article = await get_db(request).run(lambda storage: storage.load_article(article_id))
+    if article is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="unknown article")
+    return article
+
+
+def _page(
+    request: Request, template: str, context: dict[str, object], status_code: int = 200
+) -> object:
+    return request.app.state.templates.TemplateResponse(
+        request, template, {"active_section": "articles", **context}, status_code=status_code
+    )
+
+
+@router.get("")
+async def articles_list(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    articles = await get_db(request).run(lambda storage: storage.load_all_articles())
+    return _page(
+        request,
+        "articles_list.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "articles": articles,
+            "target_languages": TARGET_LANGUAGES,
+        },
+    )
+
+
+@router.get("/new")
+async def article_new_form(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    form = {"id": "", "category": "", "tags": "", "cover": "", **content_form(None)}
+    return _page(
+        request,
+        "article_new.html.j2",
+        {"user": user, "csrf_token": session.csrf_token, "errors": [], "form": form},
+    )
+
+
+def _validated_article(base: Article, form: dict[str, str]) -> Article:
+    """Rebuild the article from the form and run every model validator once."""
+    payload = base.model_dump()
+    payload.update(
+        source=ArticleContent(
+            title=form["title"],
+            summary=form["summary"],
+            body_markdown=form["body_markdown"],
+            slug=form["slug"] or None,
+        ).model_dump(),
+        category=form["category"] or None,
+        cover=form["cover"] or None,
+        tags=parse_tags(form["tags"]),
+        updated_at=datetime.now(UTC),
+    )
+    return Article.model_validate(payload)
+
+
+@router.post("")
+async def article_create(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    article_id: str = Form(alias="id"),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+    category: str = Form(""),
+    tags: str = Form(""),
+    cover: str = Form(""),
+) -> object:
+    user, session = user_session
+    db = get_db(request)
+    form = {
+        "id": article_id,
+        "title": title,
+        "summary": summary,
+        "body_markdown": body_markdown,
+        "slug": slug,
+        "category": category,
+        "tags": tags,
+        "cover": cover,
+    }
+    try:
+        base = new_article(article_id, ArticleContent(title=title or "-"))
+        article = _validated_article(base, form)
+    except ValidationError as error:
+        errors = form_errors(error)
+    else:
+        existing = await db.run(lambda storage: storage.load_article(article_id))
+        if existing is None:
+            await db.run(lambda storage: storage.save_article(article))
+            return RedirectResponse(
+                f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER
+            )
+        errors = [f"id: an article with id {article_id!r} already exists"]
+    return _page(
+        request,
+        "article_new.html.j2",
+        {"user": user, "csrf_token": session.csrf_token, "errors": errors, "form": form},
+        status_code=HTTP_422,
+    )
+
+
+def _editor_context(
+    article: Article, form: dict[str, str] | None = None, role: Role | None = None
+) -> dict[str, object]:
+    return {
+        "article": article,
+        "transitions": available_transitions(article.status, role) if role else [],
+        "states": article.translation_states(),
+        "target_languages": TARGET_LANGUAGES,
+        "preview_html": render_markdown(article.source.body_markdown),
+        "form": form
+        or {
+            **content_form(article.source),
+            "category": article.category or "",
+            "tags": ", ".join(article.tags),
+            "cover": article.cover or "",
+        },
+    }
+
+
+@router.get("/{article_id}")
+async def article_edit_form(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    return _page(
+        request,
+        "article_edit.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "errors": [],
+            **_editor_context(article, role=user.role),
+        },
+    )
+
+
+@router.post("/{article_id}")
+async def article_edit_save(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+    category: str = Form(""),
+    tags: str = Form(""),
+    cover: str = Form(""),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    form = {
+        "title": title,
+        "summary": summary,
+        "body_markdown": body_markdown,
+        "slug": slug,
+        "category": category,
+        "tags": tags,
+        "cover": cover,
+    }
+    try:
+        article = _validated_article(article, form)
+    except ValidationError as error:
+        return _page(
+            request,
+            "article_edit.html.j2",
+            {
+                "user": user,
+                "csrf_token": session.csrf_token,
+                "errors": form_errors(error),
+                **_editor_context(article, form, role=user.role),
+            },
+            status_code=HTTP_422,
+        )
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER)
+
+
+def _translation_context(
+    article: Article, language: Language, form: dict[str, str] | None = None
+) -> dict[str, object]:
+    translation = article.translations.get(language)
+    content = translation.content if translation else None
+    return {
+        "article": article,
+        "language": language,
+        "state": article.translation_state(language),
+        "source_preview_html": render_markdown(article.source.body_markdown),
+        "preview_html": render_markdown(content.body_markdown) if content else "",
+        "form": form or content_form(content),
+    }
+
+
+@router.get("/{article_id}/translations/{language_code}")
+async def translation_form(
+    request: Request,
+    article_id: str,
+    language_code: str,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> object:
+    user, session = user_session
+    language = _target_language(language_code)
+    article = await _load_article(request, article_id)
+    return _page(
+        request,
+        "article_translation.html.j2",
+        {
+            "user": user,
+            "csrf_token": session.csrf_token,
+            "errors": [],
+            **_translation_context(article, language),
+        },
+    )
+
+
+@router.post("/{article_id}/translations/{language_code}")
+async def translation_save(
+    request: Request,
+    article_id: str,
+    language_code: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    title: str = Form(""),
+    summary: str = Form(""),
+    body_markdown: str = Form(""),
+    slug: str = Form(""),
+) -> object:
+    user, session = user_session
+    language = _target_language(language_code)
+    article = await _load_article(request, article_id)
+    form = {"title": title, "summary": summary, "body_markdown": body_markdown, "slug": slug}
+    try:
+        content = ArticleContent(
+            title=title, summary=summary, body_markdown=body_markdown, slug=slug or None
+        )
+    except ValidationError as error:
+        return _page(
+            request,
+            "article_translation.html.j2",
+            {
+                "user": user,
+                "csrf_token": session.csrf_token,
+                "errors": form_errors(error),
+                **_translation_context(article, language, form),
+            },
+            status_code=HTTP_422,
+        )
+    article.set_translation(language, content)
+    article.updated_at = datetime.now(UTC)
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(
+        f"/articles/{article.id}/translations/{language.value}",
+        status_code=status.HTTP_303_SEE_OTHER,
+    )
+
+
+@router.post("/{article_id}/status")
+async def article_status(
+    request: Request,
+    article_id: str,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+    to: str = Form(...),
+) -> object:
+    user, session = user_session
+    article = await _load_article(request, article_id)
+    try:
+        target = ContentStatus(to)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="unknown status") from None
+    minimum = transition_minimum(article.status, target)
+    if minimum is None:
+        raise HTTPException(status_code=400, detail="invalid transition")
+    if not allowed(user.role, minimum):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"requires the {minimum.value} role",
+        )
+    if target is ContentStatus.PUBLISHED and request.app.state.settings.publish_gate:
+        db = get_db(request)
+        content = SiteContent(
+            articles=await db.run(lambda storage: storage.load_all_articles()),
+            pages=await db.run(lambda storage: storage.load_all_pages()),
+            media=await db.run(lambda storage: storage.load_all_media_assets()),
+        )
+        blockers = publish_blockers(article, content)
+        if blockers:
+            return _page(
+                request,
+                "article_edit.html.j2",
+                {
+                    "user": user,
+                    "csrf_token": session.csrf_token,
+                    "errors": blockers,
+                    **_editor_context(article, role=user.role),
+                },
+                status_code=HTTP_422,
+            )
+    article.status = target
+    article.updated_at = datetime.now(UTC)
+    await get_db(request).run(lambda storage: storage.save_article(article))
+    return RedirectResponse(f"/articles/{article.id}", status_code=status.HTTP_303_SEE_OTHER)

cms_admin/auth.py

@@ -0,0 +1,186 @@
+"""Authentication and access control (SECURITY_STRATEGY, admin section).
+
+Server-side sessions in the storage database (revocable, engine-agnostic),
+session cookie ``HttpOnly`` + ``SameSite=Strict`` (+ ``Secure`` outside
+local development), synchronizer CSRF tokens on authenticated state-changing
+requests, a double-submit token on the login form itself, and per-process
+rate limiting on failed logins.
+"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from cms_core.accounts import AdminSession, Role, User
+from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
+from fastapi.responses import RedirectResponse
+
+from cms_admin.db import StorageExecutor
+from cms_admin.security import new_token, token_digest, verify_password
+
+SESSION_COOKIE = "sardine_session"
+LOGIN_CSRF_COOKIE = "sardine_login_csrf"
+
+# Least-privilege ladder (cms_core.accounts.Role docstring).
+ROLE_ORDER = (Role.EDITOR, Role.REVIEWER, Role.PUBLISHER, Role.ADMIN)
+
+router = APIRouter()
+
+
+@dataclass
+class LoginRateLimiter:
+    """Per-process failed-login limiter, keyed by username and client host."""
+
+    max_failures: int = 5
+    window: timedelta = timedelta(minutes=15)
+    _failures: dict[str, list[datetime]] = field(default_factory=dict)
+
+    def is_blocked(self, key: str, now: datetime) -> bool:
+        recent = [moment for moment in self._failures.get(key, []) if now - moment < self.window]
+        if recent:
+            self._failures[key] = recent
+        else:
+            self._failures.pop(key, None)
+        return len(recent) >= self.max_failures
+
+    def record_failure(self, key: str, now: datetime) -> None:
+        self._failures.setdefault(key, []).append(now)
+
+    def reset(self, key: str) -> None:
+        self._failures.pop(key, None)
+
+
+def get_db(request: Request) -> StorageExecutor:
+    db: StorageExecutor = request.app.state.db
+    return db
+
+
+def _login_redirect() -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_303_SEE_OTHER, headers={"Location": "/login"}, detail="sign in"
+    )
+
+
+async def current_session(request: Request) -> tuple[User, AdminSession]:
+    token = request.cookies.get(SESSION_COOKIE)
+    if not token:
+        raise _login_redirect()
+    digest = token_digest(token)
+    now = datetime.now(UTC)
+    db = get_db(request)
+    session = await db.run(lambda storage: storage.load_session(digest))
+    if session is None or session.expires_at <= now:
+        raise _login_redirect()
+    user = await db.run(lambda storage: storage.load_user(session.username))
+    if user is None:
+        raise _login_redirect()
+    return user, session
+
+
+def require_at_least(minimum: Role) -> Callable[..., Awaitable[User]]:
+    async def dependency(
+        user_session: tuple[User, AdminSession] = Depends(current_session),
+    ) -> User:
+        user, _ = user_session
+        if ROLE_ORDER.index(user.role) < ROLE_ORDER.index(minimum):
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="insufficient role")
+        return user
+
+    return dependency
+
+
+async def enforce_csrf(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(current_session),
+) -> tuple[User, AdminSession]:
+    form = await request.form()
+    token = form.get("csrf_token")
+    _, session = user_session
+    if not isinstance(token, str) or token != session.csrf_token:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="invalid CSRF token")
+    return user_session
+
+
+def _client_key(request: Request, username: str) -> str:
+    host = request.client.host if request.client else "unknown"
+    return f"{username.lower()}|{host}"
+
+
+@router.get("/login")
+async def login_form(request: Request) -> object:
+    csrf = new_token()
+    response = request.app.state.templates.TemplateResponse(
+        request, "login.html.j2", {"error": None, "login_csrf": csrf}
+    )
+    response.set_cookie(
+        LOGIN_CSRF_COOKIE,
+        csrf,
+        httponly=True,
+        samesite="strict",
+        secure=request.app.state.settings.cookie_secure,
+    )
+    return response
+
+
+@router.post("/login")
+async def login_submit(
+    request: Request,
+    username: str = Form(...),
+    password: str = Form(...),
+    login_csrf: str = Form(...),
+) -> object:
+    settings = request.app.state.settings
+    if request.cookies.get(LOGIN_CSRF_COOKIE) != login_csrf:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="invalid CSRF token")
+    now = datetime.now(UTC)
+    limiter: LoginRateLimiter = request.app.state.login_limiter
+    key = _client_key(request, username)
+    if limiter.is_blocked(key, now):
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="too many failed attempts; try again later",
+        )
+    db = get_db(request)
+    user = await db.run(lambda storage: storage.load_user(username))
+    if user is None or not verify_password(user.password_hash, password):
+        limiter.record_failure(key, now)
+        response = request.app.state.templates.TemplateResponse(
+            request,
+            "login.html.j2",
+            {"error": "Wrong username or password.", "login_csrf": login_csrf},
+            status_code=status.HTTP_401_UNAUTHORIZED,
+        )
+        return response
+    limiter.reset(key)
+    token = new_token()
+    session = AdminSession(
+        token_hash=token_digest(token),
+        username=user.username,
+        csrf_token=new_token(),
+        expires_at=now + settings.session_ttl,
+    )
+    await db.run(lambda storage: storage.save_session(session))
+    await db.run(lambda storage: storage.delete_expired_sessions(now))
+    response = RedirectResponse("/", status_code=status.HTTP_303_SEE_OTHER)
+    response.set_cookie(
+        SESSION_COOKIE,
+        token,
+        max_age=int(settings.session_ttl.total_seconds()),
+        httponly=True,
+        samesite="strict",
+        secure=settings.cookie_secure,
+    )
+    response.delete_cookie(LOGIN_CSRF_COOKIE)
+    return response
+
+
+@router.post("/logout")
+async def logout(
+    request: Request,
+    user_session: tuple[User, AdminSession] = Depends(enforce_csrf),
+) -> RedirectResponse:
+    _, session = user_session
+    await get_db(request).run(lambda storage: storage.delete_session(session.token_hash))
+    response = RedirectResponse("/login", status_code=status.HTTP_303_SEE_OTHER)
+    response.delete_cookie(SESSION_COOKIE)
+    return response