toolframe-web 0.1.0__py3-none-any.whl

toolframe_web/__init__.py

@@ -0,0 +1,5 @@
+"""HTML helpers for Toolframe Web app authors."""
+
+from .render import asset_tags, html, json, redirect, render
+
+__all__ = ["asset_tags", "html", "json", "redirect", "render"]

toolframe_web/asset_delivery.py

@@ -0,0 +1,51 @@
+"""Authorized delivery of current and retained sealed assets."""
+
+import asyncio
+import hashlib
+
+from starlette.responses import Response
+from toolframe_sdk import PluginError
+
+from .assets import AssetSet
+from .policy import asset_policy
+
+
+async def deliver_asset(provider, request, app, key, epoch, reference):
+    asset = request.scope["path"].removeprefix("/_tf/assets/")
+    admission = await provider.context.resource_admit(
+        key, None, epoch=epoch, access_context=reference, asset=asset
+    )
+    checksum, _, path = asset.partition("/")
+    assets = app.assets
+    if checksum != assets.manifest.digest:
+        if provider.cache is None:
+            raise PluginError("web_asset_missing", "Previous asset set is unavailable")
+        assets = await asyncio.to_thread(AssetSet.cached, provider.cache, checksum)
+    item = next((file for file in assets.manifest.files if file.path == path), None)
+    if item is None:
+        raise PluginError("web_asset_missing", "Asset is not declared")
+    policy = asset_policy(app.catalog, item)
+    # Capabilities may change without changing asset bytes. Revalidate scripts
+    # with a validator that includes the current policy, including retained sets.
+    script = item.media_type == "text/javascript"
+    etag = '"' + hashlib.sha256((item.sha256 + policy).encode()).hexdigest() + '"'
+    cache_control = "private, no-store"
+    if admission["visibility"] == "public":
+        cache_control = (
+            "public, max-age=0, must-revalidate"
+            if script
+            else "public, max-age=31536000, immutable"
+        )
+    headers = {
+        "ETag": etag,
+        "X-Content-Type-Options": "nosniff",
+        "Cache-Control": cache_control,
+        "Content-Security-Policy": policy,
+    }
+    if request.headers.get("if-none-match") == etag:
+        return Response(status_code=304, headers=headers)
+    return Response(
+        b"" if request.method == "HEAD" else assets.content[path],
+        media_type=item.media_type,
+        headers=headers,
+    )

toolframe_web/assets.py

@@ -0,0 +1,205 @@
+"""Sealed, allowlisted browser asset sets. Runtime never downloads or builds."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.resources
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import Field, field_validator, model_validator
+from toolframe_sdk import PluginError, digest
+from toolframe_sdk.contracts import Contract
+from toolframe_sdk.web import relative_file
+
+MEDIA_TYPES = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css",
+    ".html": "text/html",
+    ".json": "application/json",
+    ".map": "application/json",
+    ".wasm": "application/wasm",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".txt": "text/plain",
+}
+MAX_FILE = 8 * 1024 * 1024
+MAX_SET = 32 * 1024 * 1024
+
+
+def media_type(path):
+    try:
+        return MEDIA_TYPES[Path(path).suffix.lower()]
+    except KeyError:
+        raise ValueError(f"Unsupported public asset extension: {path}") from None
+
+
+class AssetFile(Contract):
+    path: str
+    sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+    size: int = Field(ge=0, le=MAX_FILE)
+    media_type: str
+    source: str = "local"
+    license: str | None = None
+    dependencies: tuple[str, ...] = ()
+
+    @model_validator(mode="after")
+    def paths(self):
+        relative_file(self.path)
+        if self.media_type != media_type(self.path):
+            raise ValueError("Asset MIME type must match its declared file extension")
+        for value in self.dependencies:
+            relative_file(value)
+        if self.license:
+            relative_file(self.license)
+        return self
+
+
+class Document(Contract):
+    styles: tuple[str, ...] = ()
+    scripts: tuple[str, ...] = ()
+    modules: tuple[str, ...] = ()
+    imports: dict[str, str] = Field(default_factory=dict)
+    visibility: str = "inherit"
+
+    @field_validator("visibility")
+    @classmethod
+    def visibility_value(cls, value):
+        if value not in {"inherit", "public"}:
+            raise ValueError("Asset visibility must be inherit or public")
+        return value
+
+
+class Manifest(Contract):
+    schema_version: int = Field(default=1, ge=1, le=1)
+    public: str = "web/public"
+    document: Document = Field(default_factory=Document)
+    files: tuple[AssetFile, ...]
+    recipe: dict = Field(default_factory=dict)
+    digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+
+    @model_validator(mode="after")
+    def sealed(self):
+        relative_file(self.public)
+        paths = {item.path for item in self.files}
+        if (
+            len(self.files) > 2048
+            or len(paths) != len(self.files)
+            or len({path.casefold() for path in paths}) != len(paths)
+        ):
+            raise ValueError("Asset paths must be distinct and bounded")
+        if sum(item.size for item in self.files) > MAX_SET:
+            raise ValueError("Asset set exceeds 32 MiB")
+        referenced = {
+            *self.document.styles,
+            *self.document.scripts,
+            *self.document.modules,
+            *self.document.imports.values(),
+        }
+        referenced |= {path for item in self.files for path in item.dependencies}
+        referenced |= {item.license for item in self.files if item.license}
+        if not referenced <= paths:
+            raise ValueError("Manifest references an undeclared asset or license")
+        if any(media_type(path) != "text/css" for path in self.document.styles):
+            raise ValueError("Style entries must be CSS")
+        if any(
+            media_type(path) != "text/javascript"
+            for path in (
+                *self.document.scripts,
+                *self.document.modules,
+                *self.document.imports.values(),
+            )
+        ):
+            raise ValueError("Script and import entries must be JavaScript")
+        if self.digest != digest(self.model_dump(mode="json", exclude={"digest"})):
+            raise ValueError("Asset manifest digest mismatch")
+        return self
+
+
+def seal(public, files, *, document=None, recipe=None):
+    payload = {
+        "schema_version": 1,
+        "public": public,
+        "document": (document or Document()).model_dump(mode="json"),
+        "files": [
+            item.model_dump(mode="json")
+            for item in sorted(files, key=lambda item: item.path)
+        ],
+        "recipe": recipe or {},
+    }
+    return Manifest(**payload, digest=digest(payload))
+
+
+def safe_file(root, relative):
+    relative_file(relative)
+    root = Path(root).resolve()
+    path = root.joinpath(relative)
+    if not path.resolve().is_relative_to(root) or any(
+        parent.is_symlink()
+        for parent in (path, *path.parents)
+        if parent != root and parent.is_relative_to(root)
+    ):
+        raise ValueError("Assets cannot contain symlinks or escape their package")
+    return path
+
+
+@dataclass(frozen=True)
+class AssetSet:
+    manifest: Manifest
+    content: dict
+
+    @classmethod
+    def load(cls, package, manifest_path):
+        root = Path(str(importlib.resources.files(package)))
+        path = safe_file(root, manifest_path)
+        if path.stat().st_size > 1024 * 1024:
+            raise ValueError("Asset manifest exceeds 1 MiB")
+        manifest = Manifest.model_validate_json(path.read_bytes())
+        content = {}
+        for item in manifest.files:
+            file = safe_file(root, manifest.public + "/" + item.path)
+            if file.stat().st_size != item.size:
+                raise ValueError("Asset size mismatch")
+            value = file.read_bytes()
+            if hashlib.sha256(value).hexdigest() != item.sha256:
+                raise ValueError("Asset content hash mismatch")
+            content[item.path] = value
+        return cls(manifest, content)
+
+    def persist(self, root):
+        target = Path(root) / self.manifest.digest
+        target.mkdir(parents=True, exist_ok=True, mode=0o700)
+        for item in self.manifest.files:
+            path = safe_file(target, "public/" + item.path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(self.content[item.path])
+        (target / "manifest.json").write_text(self.manifest.model_dump_json())
+
+    @classmethod
+    def cached(cls, root, checksum):
+        if len(checksum) != 64 or any(c not in "0123456789abcdef" for c in checksum):
+            raise PluginError("web_asset_missing", "Unknown Web asset set")
+        target = Path(root) / checksum
+        manifest = Manifest.model_validate_json((target / "manifest.json").read_bytes())
+        if manifest.digest != checksum:
+            raise ValueError("Cached asset identity mismatch")
+        content = {}
+        for item in manifest.files:
+            path = safe_file(target, "public/" + item.path)
+            if path.stat().st_size != item.size:
+                raise ValueError("Cached asset size mismatch")
+            value = path.read_bytes()
+            if hashlib.sha256(value).hexdigest() != item.sha256:
+                raise ValueError("Cached asset hash mismatch")
+            content[item.path] = value
+        return cls(manifest, content)

toolframe_web/authoring.py

@@ -0,0 +1,29 @@
+"""Distribution authoring entries, independent of runtime plugin activation."""
+
+from importlib.metadata import version
+from importlib.resources import files
+
+import tomlkit
+from toolframe_sdk.authoring import render_plugin, write_template
+
+
+def generate(*, destination, parameters):
+    rendered = render_plugin(
+        files("toolframe_web").joinpath("templates/notes"),
+        parameters["name"],
+        text_suffixes=(".toml", ".html", ".js", ".md"),
+    )
+    from pathlib import Path
+
+    project = tomlkit.parse(rendered[Path("pyproject.toml")].decode())
+    requirement = "toolframe-web==" + version("toolframe-web")
+    project["project"]["optional-dependencies"]["web"] = [requirement]
+    project["tool"]["toolframe"] = {"authoring": {"source": "pypi:" + requirement}}
+    rendered[Path("pyproject.toml")] = tomlkit.dumps(project).encode()
+    write_template(destination, rendered)
+
+
+def prepare(*, source, destination, cache, offline):
+    from .prepare import stage
+
+    return stage(source, destination, cache, offline=offline)

toolframe_web/cli.py

@@ -0,0 +1,29 @@
+"""Private build adapter and standalone author-time staging command."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .prepare import stage
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="toolframe-web")
+    commands = parser.add_subparsers(dest="command", required=True)
+    prepare = commands.add_parser("stage")
+    prepare.add_argument("source", type=Path)
+    prepare.add_argument("destination", type=Path)
+    prepare.add_argument("--cache", type=Path, required=True)
+    prepare.add_argument("--offline", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        print(
+            json.dumps(
+                stage(args.source, args.destination, args.cache, offline=args.offline)
+            )
+        )
+    except (OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}), file=sys.stderr)
+        return 1
+    return 0