web-edit 0.1a0__py3-none-any.whl

web_edit/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

web_edit/app.py

@@ -0,0 +1,171 @@
+"""Starlette application factory used by the CLI and embedders."""
+
+import json
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.concurrency import run_in_threadpool
+from starlette.datastructures import UploadFile
+from starlette.responses import FileResponse, JSONResponse
+from starlette.routing import Mount, Route
+from starlette.staticfiles import StaticFiles
+
+from .files import IMAGE_LIMIT, TEXT_LIMIT, FileError, FileStore
+from .security import allowed_hosts_for, is_allowed_host
+
+STATIC = Path(__file__).parent / "static"
+
+
+class BrowserProtection:
+    """Check hosts against DNS rebinding and require a non-simple write header."""
+
+    def __init__(self, app, allowed_hosts):
+        self.app = app
+        self.allowed_hosts = allowed_hosts
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            if not is_allowed_host(scope["headers"], self.allowed_hosts):
+                await JSONResponse(
+                    {
+                        "error": "Host not allowed. Configure --allowed-host to allow an additional hostname or IP address."
+                    },
+                    status_code=400,
+                    headers={"Cache-Control": "no-store"},
+                )(scope, receive, send)
+                return
+            headers = dict(scope["headers"])
+            if (
+                scope["method"] not in {"GET", "HEAD", "OPTIONS"}
+                and headers.get(b"x-web-edit") != b"1"
+            ):
+                await JSONResponse(
+                    {"error": "Missing X-Web-Edit header."}, status_code=403
+                )(scope, receive, send)
+                return
+
+            async def secure_send(message):
+                if message["type"] == "http.response.start":
+                    message.setdefault("headers", []).extend(
+                        [
+                            (b"x-content-type-options", b"nosniff"),
+                            (b"cache-control", b"no-store"),
+                            (b"referrer-policy", b"no-referrer"),
+                        ]
+                    )
+                await send(message)
+
+            await self.app(scope, receive, secure_send)
+        else:
+            await self.app(scope, receive, send)
+
+
+async def handle_error(request, error):
+    if isinstance(error, FileError):
+        return JSONResponse(
+            {"error": str(error), **error.details}, status_code=error.status
+        )
+    if isinstance(error, FileNotFoundError):
+        return JSONResponse({"error": "File or folder not found."}, status_code=404)
+    if isinstance(error, PermissionError):
+        return JSONResponse(
+            {"error": "Permission denied for this file or folder."}, status_code=403
+        )
+    return JSONResponse(
+        {"error": "The filesystem operation could not be completed."}, status_code=400
+    )
+
+
+def create_app(directory=".", *, host="127.0.0.1", allowed_hosts=()):
+    trusted_hosts = allowed_hosts_for(host, allowed_hosts)
+    store = FileStore(directory)
+
+    def index(request):
+        return FileResponse(
+            STATIC / "index.html",
+            headers={
+                "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; base-uri 'self'; frame-ancestors 'none'",
+            },
+        )
+
+    def browse(request):
+        return JSONResponse(store.browse(request.query_params.get("path", "")))
+
+    def read_text(request):
+        return JSONResponse(store.text(request.query_params.get("path", "")))
+
+    async def save_text(request):
+        # Bound JSON before decoding, allowing for JSON's escaped representation.
+        chunks = bytearray()
+        async for chunk in request.stream():
+            chunks.extend(chunk)
+            if len(chunks) > TEXT_LIMIT * 6 + 8192:
+                raise FileError("Text editing is limited to 10 MiB.", 413)
+        try:
+            body = json.loads(chunks)
+        except (ValueError, UnicodeDecodeError):
+            raise FileError("Invalid JSON.")
+        if not isinstance(body, dict) or "path" not in body or "content" not in body:
+            raise FileError("Provide path and content.")
+        result = await run_in_threadpool(
+            store.save_text, body["path"], body["content"], body.get("version")
+        )
+        return JSONResponse(result)
+
+    async def upload(request):
+        async with request.form(max_files=1, max_fields=2) as form:
+            file = form.get("file")
+            relative = form.get("path")
+            expected = form.get("version")
+            if not isinstance(file, UploadFile) or not isinstance(relative, str):
+                raise FileError("Provide a file and destination path.")
+            if expected is not None and not isinstance(expected, str):
+                raise FileError("Invalid version.")
+            result = await run_in_threadpool(store.write, relative, file.file, expected)
+            return JSONResponse(result, status_code=201)
+
+    def download(request):
+        path = store.regular_file(request.query_params.get("path", ""))
+        return FileResponse(
+            path, filename=path.name, media_type="application/octet-stream"
+        )
+
+    def delete(request):
+        return JSONResponse(
+            store.delete(
+                request.query_params.get("path", ""),
+                request.query_params.get("kind"),
+                request.query_params.get("version"),
+            )
+        )
+
+    def image(request):
+        path = store.regular_file(request.query_params.get("path", ""))
+        mime = store.image_type(path)
+        if not mime or path.stat().st_size >= IMAGE_LIMIT:
+            raise FileError(
+                "Image previews are available for images smaller than 2 MB.", 415
+            )
+        return FileResponse(
+            path,
+            media_type=mime,
+            headers={"Content-Security-Policy": "sandbox; default-src 'none'"},
+        )
+
+    app = Starlette(
+        routes=[
+            Route("/", index),
+            Route("/api/browse", browse),
+            Route("/api/text", read_text, methods=["GET"]),
+            Route("/api/text", save_text, methods=["PUT"]),
+            Route("/api/upload", upload, methods=["POST"]),
+            Route("/api/download", download),
+            Route("/api/file", delete, methods=["DELETE"]),
+            Route("/api/image", image),
+            Mount("/static", StaticFiles(directory=STATIC), name="static"),
+        ],
+        exception_handlers={FileError: handle_error, OSError: handle_error},
+    )
+    app.add_middleware(BrowserProtection, allowed_hosts=trusted_hosts)
+    app.state.store = store
+    return app

web_edit/cli.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+
+import click
+import uvicorn
+
+from .app import create_app
+from .security import normalize_host
+
+
+def validate_host(ctx, param, value):
+    try:
+        if param.multiple:
+            return tuple(normalize_host(host) for host in value)
+        return normalize_host(value)
+    except ValueError as error:
+        raise click.BadParameter(str(error), ctx=ctx, param=param) from error
+
+
+@click.command()
+@click.version_option()
+@click.argument(
+    "directory",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+@click.option(
+    "--host",
+    "-h",
+    default="127.0.0.1",
+    show_default=True,
+    callback=validate_host,
+    help="Address to listen on.",
+)
+@click.option(
+    "--allowed-host",
+    "-a",
+    "allowed_hosts",
+    multiple=True,
+    callback=validate_host,
+    metavar="HOSTNAME",
+    help="Additional hostname or IP to accept. Repeat for multiple hosts. Required for remote access when listening on 0.0.0.0 or ::.",
+)
+@click.option(
+    "--port", "-p", default=9000, type=click.IntRange(1, 65535), show_default=True
+)
+def cli(directory, host, port, allowed_hosts):
+    "Browse and edit files in DIRECTORY (defaults to the current folder)."
+    url_host = f"[{host}]" if ":" in host else host
+    click.echo(f"Serving {directory.resolve()} at http://{url_host}:{port}")
+    uvicorn.run(
+        create_app(directory, host=host, allowed_hosts=allowed_hosts),
+        host=host,
+        port=port,
+    )

web_edit/files.py

@@ -0,0 +1,289 @@
+"""Filesystem operations, confined to one root directory."""
+
+import hashlib
+import mimetypes
+import os
+import re
+import shutil
+import stat
+import tempfile
+import threading
+from collections import Counter
+from difflib import SequenceMatcher
+from pathlib import Path, PurePosixPath
+
+IMAGE_LIMIT = 2_000_000
+TEXT_LIMIT = 10 * 1024 * 1024
+IMAGE_TYPES = {
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "image/bmp",
+    "image/x-icon",
+    "image/vnd.microsoft.icon",
+    "image/svg+xml",
+}
+
+
+class FileError(Exception):
+    def __init__(self, message, status=400, **details):
+        super().__init__(message)
+        self.status = status
+        self.details = details
+
+
+def version(path):
+    # Content hashes ignore metadata-only changes from sync tools like Dropbox.
+    with path.open("rb") as source:
+        return hashlib.file_digest(source, "sha256").hexdigest()
+
+
+def delete_version(info):
+    """Identify the item shown in a listing without reading file contents."""
+    value = f"{info.st_dev}:{info.st_ino}:{info.st_mtime_ns}:{info.st_size}:{stat.S_IFMT(info.st_mode)}"
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def decode_text(data):
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise FileError(
+            "This file is not UTF-8 text. You can download it instead.", 415
+        )
+    if re.search(r"[\x00-\x08\x0b\x0c\x0e-\x1f]", text):
+        raise FileError(
+            "This looks like a binary file. You can download it instead.", 415
+        )
+    return text
+
+
+def preserve_endings(original, edited):
+    """Keep the endings of unchanged lines, including files with mixed endings."""
+    old_lines = re.split(r"\r\n|\r|\n", original)
+    old_endings = re.findall(r"\r\n|\r|\n", original)
+    new_lines = re.split(r"\r\n|\r|\n", edited)
+    default = Counter(old_endings).most_common(1)[0][0] if old_endings else "\n"
+    endings = [default] * (len(new_lines) - 1)
+    # SequenceMatcher's autojunk heuristic handles repetitive documents.
+    for match in SequenceMatcher(None, old_lines, new_lines).get_matching_blocks():
+        for offset in range(match.size):
+            old_index, new_index = match.a + offset, match.b + offset
+            if old_index < len(old_endings) and new_index < len(endings):
+                endings[new_index] = old_endings[old_index]
+    return "".join(
+        line + (endings[i] if i < len(endings) else "")
+        for i, line in enumerate(new_lines)
+    )
+
+
+class FileStore:
+    def __init__(self, root):
+        self.root = Path(root).resolve(strict=True)
+        if not self.root.is_dir():
+            raise ValueError("The root must be a directory")
+        self.lock = threading.RLock()
+
+    def path(self, relative, *, file=False):
+        if not isinstance(relative, str) or "\x00" in relative or "\\" in relative:
+            raise FileError("Invalid path.")
+        try:
+            relative.encode("utf-8")
+        except UnicodeEncodeError:
+            raise FileError("Invalid path.")
+        parts = PurePosixPath(relative)
+        if parts.is_absolute() or ".." in parts.parts:
+            raise FileError("Paths must stay inside the root folder.", 403)
+        if file and (not parts.parts or relative.endswith("/")):
+            raise FileError("Choose a filename.")
+        result = self.root
+        for part in parts.parts:
+            result = result / part
+            if result.is_symlink():
+                raise FileError("Symbolic links are not followed.", 403)
+        if not result.resolve().is_relative_to(self.root):
+            raise FileError("Paths must stay inside the root folder.", 403)
+        return result
+
+    def regular_file(self, relative):
+        path = self.path(relative, file=True)
+        if not stat.S_ISREG(path.stat().st_mode):
+            raise FileError("This is not a regular file.")
+        return path
+
+    def image_type(self, path):
+        mime = mimetypes.guess_type(path.name)[0]
+        return mime if mime in IMAGE_TYPES else None
+
+    def browse(self, relative):
+        folder = self.path(relative)
+        if not folder.is_dir():
+            if not folder.exists():
+                raise FileNotFoundError()
+            raise FileError("This is not a folder.")
+        entries = []
+        for child in folder.iterdir():
+            if child.name.startswith(".web-edit-"):
+                continue
+            try:
+                info = child.lstat()
+            except FileNotFoundError:
+                continue
+            kind = "directory" if stat.S_ISDIR(info.st_mode) else "file"
+            if stat.S_ISLNK(info.st_mode):
+                kind = "symlink"
+            elif not (stat.S_ISDIR(info.st_mode) or stat.S_ISREG(info.st_mode)):
+                kind = "special"
+            entries.append(
+                {
+                    "name": child.name,
+                    "path": child.relative_to(self.root).as_posix(),
+                    "kind": kind,
+                    "size": info.st_size,
+                    "modified": info.st_mtime,
+                    "delete_version": delete_version(info),
+                    "preview": kind == "file"
+                    and info.st_size < IMAGE_LIMIT
+                    and bool(self.image_type(child)),
+                }
+            )
+        entries.sort(
+            key=lambda item: (
+                item["kind"] != "directory",
+                item["name"].casefold(),
+                item["name"],
+            )
+        )
+        return {
+            "path": ""
+            if folder == self.root
+            else folder.relative_to(self.root).as_posix(),
+            "root_name": self.root.name or "/",
+            "entries": entries,
+        }
+
+    def delete(self, relative, kind, expected):
+        with self.lock:
+            target = self.path(relative)
+            if target == self.root:
+                raise FileError("The root folder cannot be deleted.", 403)
+            if kind not in {"file", "directory"} or not expected:
+                raise FileError(
+                    "Provide the item kind and version from the folder listing."
+                )
+            info = target.lstat()
+            actual_kind = "directory" if stat.S_ISDIR(info.st_mode) else "file"
+            if not (stat.S_ISDIR(info.st_mode) or stat.S_ISREG(info.st_mode)):
+                raise FileError("Only regular files and folders can be deleted.", 403)
+            if kind != actual_kind or expected != delete_version(info):
+                raise FileError(
+                    "This item changed since the folder was loaded. Refresh before deleting it.",
+                    409,
+                )
+            if kind == "directory":
+                # rmtree removes child symlinks themselves, never their targets.
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+            return {"path": relative, "deleted": True}
+
+    def text(self, relative):
+        with self.lock:
+            path = self.regular_file(relative)
+            before = version(path)
+            if path.stat().st_size > TEXT_LIMIT:
+                raise FileError(
+                    "Text editing is limited to 10 MiB. You can download this file.",
+                    413,
+                )
+            data = path.read_bytes()
+            if version(path) != before:
+                raise FileError(
+                    "The file changed while opening it. Please try again.", 409
+                )
+            return {"path": relative, "content": decode_text(data), "version": before}
+
+    def check_destination(self, relative, expected):
+        path = self.path(relative, file=True)
+        if path.exists():
+            if not path.is_file():
+                raise FileError(
+                    "A folder or special file already exists at that path.", 409
+                )
+            current = version(path)
+            if expected != current:
+                raise FileError(
+                    "This file already exists or has changed on disk.",
+                    409,
+                    version=current,
+                    exists=True,
+                )
+        elif expected is not None:
+            raise FileError(
+                "The file was removed or moved on disk. Save your work to a new path.",
+                409,
+            )
+        return path
+
+    def write(self, relative, source, expected=None):
+        with self.lock:
+            target = self.check_destination(relative, expected)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            self.path(relative, file=True)
+            temporary = None
+            try:
+                with tempfile.NamedTemporaryFile(
+                    prefix=".web-edit-", dir=target.parent, delete=False
+                ) as output:
+                    temporary = Path(output.name)
+                    shutil.copyfileobj(source, output, length=1024 * 1024)
+                    output.flush()
+                    os.fsync(output.fileno())
+                self.check_destination(relative, expected)
+                if expected is None:
+                    # link is an atomic create-if-absent; never silently replace a file.
+                    try:
+                        os.link(temporary, target)
+                    except FileExistsError:
+                        raise FileError(
+                            "A file appeared at this path during the upload. Please retry.",
+                            409,
+                        )
+                else:
+                    os.chmod(temporary, stat.S_IMODE(target.stat().st_mode))
+                    os.replace(temporary, target)
+            finally:
+                if temporary is not None:
+                    temporary.unlink(missing_ok=True)
+            return {"path": relative, "version": version(target)}
+
+    def save_text(self, relative, content, expected):
+        from io import BytesIO
+
+        if not isinstance(content, str) or (
+            expected is not None and not isinstance(expected, str)
+        ):
+            raise FileError(
+                "Content must be text and version must be a string or null."
+            )
+        try:
+            encoded = content.encode("utf-8")
+        except UnicodeEncodeError:
+            raise FileError("Content must be valid UTF-8 text.")
+        if len(encoded) > TEXT_LIMIT:
+            raise FileError("Text editing is limited to 10 MiB.", 413)
+        decode_text(encoded)
+        with self.lock:
+            path = self.check_destination(relative, expected)
+            if expected is not None:
+                if path.stat().st_size > TEXT_LIMIT:
+                    raise FileError("Text editing is limited to 10 MiB.", 413)
+                original = path.read_bytes()
+                encoded = preserve_endings(decode_text(original), content).encode(
+                    "utf-8"
+                )
+                if original.startswith(b"\xef\xbb\xbf"):
+                    encoded = b"\xef\xbb\xbf" + encoded
+            return self.write(relative, BytesIO(encoded), expected)

web_edit/security.py

@@ -0,0 +1,56 @@
+"""Exact host matching for requests to the unauthenticated file server."""
+
+import ipaddress
+import re
+
+LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+UNSPECIFIED_HOSTS = {"0.0.0.0", "::"}
+HOST_HEADER = re.compile(r"(?:\[([0-9a-fA-F:.]+)\]|([a-zA-Z0-9.-]+))(?::([0-9]{1,5}))?")
+DNS_LABEL = re.compile(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?")
+
+
+def normalize_host(value):
+    """Accept an IP or exact DNS name, without a scheme, port, or wildcard."""
+    try:
+        return str(ipaddress.ip_address(value))
+    except ValueError:
+        pass
+    try:
+        name = value.encode("idna").decode("ascii").lower().removesuffix(".")
+    except UnicodeError:
+        name = ""
+    if (
+        not name
+        or len(name) > 253
+        or not all(DNS_LABEL.fullmatch(label) for label in name.split("."))
+    ):
+        raise ValueError(
+            "Use an IP address or exact hostname, without a scheme, port, path, or wildcard."
+        )
+    return name
+
+
+def allowed_hosts_for(host, extra_hosts=()):
+    hosts = LOCAL_HOSTS | {normalize_host(name) for name in extra_hosts}
+    bound_host = normalize_host(host)
+    # Listening on every interface must not mean trusting every Host header.
+    if bound_host not in UNSPECIFIED_HOSTS:
+        hosts.add(bound_host)
+    return frozenset(hosts)
+
+
+def is_allowed_host(headers, allowed_hosts):
+    values = [value for name, value in headers if name.lower() == b"host"]
+    if len(values) != 1:
+        return False
+    try:
+        match = HOST_HEADER.fullmatch(values[0].decode("ascii"))
+        if match is None:
+            return False
+        ipv6, hostname, port = match.groups()
+        if port is not None and not 1 <= int(port) <= 65535:
+            return False
+        host = str(ipaddress.IPv6Address(ipv6)) if ipv6 else normalize_host(hostname)
+    except (ValueError, UnicodeError):
+        return False
+    return host in allowed_hosts