@openthread/claude-code-plugin 0.1.4 → 0.1.8

package/scripts/lib/export_client.py

@@ -0,0 +1,666 @@
+"""Download an OpenThread post as a local archive file.
+
+Invoked by ``scripts/export.sh``. Reads its configuration from
+environment variables and either writes a file to disk (mode ``0644``,
+atomic rename from ``<path>.part``) or streams the body to stdout.
+
+The file is meant for archival / sharing — the provenance banner is
+plain (no "untrusted data" warning) and the mode allows other users
+on the machine to read it. The body is still re-masked locally with
+the shared ``sanitize`` + ``mask`` libraries as defense-in-depth on
+top of the server's ingest-time masking.
+
+Error reporting: this script never raises an uncaught exception. On
+any failure it prints a single JSON object to stderr of the form
+``{"error": "<CODE>", "message": "..."}`` and exits with a non-zero
+status code. Success always ends with a single JSON object on stdout
+(or on stderr if ``STDOUT=1``, so the body stream remains clean).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import socket
+import ssl
+import sys
+import tempfile
+import unicodedata
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any
+
+# Allow ``from lib import ...`` when invoked as a standalone script.
+_SCRIPTS_DIR = os.environ.get("PLUGIN_SCRIPTS_DIR")
+if _SCRIPTS_DIR and _SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPTS_DIR)
+
+try:
+    from lib import mask as mask_mod  # type: ignore
+    from lib import sanitize as sanitize_mod  # type: ignore
+except ImportError:  # pragma: no cover - fallback for direct invocation
+    import mask as mask_mod  # type: ignore
+    import sanitize as sanitize_mod  # type: ignore
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MAX_RESPONSE_BYTES = 5 * 1024 * 1024  # 5 MB, matches the server cap
+READ_CHUNK = 64 * 1024
+REQUEST_TIMEOUT = 30  # seconds
+
+VALID_FORMATS = frozenset({"markdown", "text", "json"})
+
+FORMAT_EXT = {
+    "markdown": "md",
+    "text": "txt",
+    "json": "json",
+}
+
+# Absolute paths that land inside any of these directories are refused
+# even if the user explicitly asked for them. Export is user-facing so
+# we pick a conservative denylist that still allows ``~``, ``/tmp``,
+# ``/private/tmp``, ``/Users``, ``/home``, etc.
+SYSTEM_DENYLIST = (
+    "/etc/",
+    "/dev/",
+    "/proc/",
+    "/sys/",
+    "/bin/",
+    "/sbin/",
+    "/usr/",
+    "/var/",
+    "/boot/",
+    "/lib/",
+    "/lib64/",
+)
+
+UUID_RE = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Error helpers
+# ---------------------------------------------------------------------------
+
+
+def _emit_error(code: str, message: str, extra: dict[str, Any] | None = None) -> None:
+    payload: dict[str, Any] = {"error": code, "message": message}
+    if extra:
+        payload.update(extra)
+    sys.stderr.write(json.dumps(payload) + "\n")
+    sys.stderr.flush()
+
+
+def _fail(code: str, message: str, extra: dict[str, Any] | None = None) -> None:
+    _emit_error(code, message, extra)
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Input parsing
+# ---------------------------------------------------------------------------
+
+
+def extract_uuid(raw: str) -> str | None:
+    """Pull the first UUID out of a bare UUID, path, or full URL."""
+    if not raw:
+        return None
+    match = UUID_RE.search(raw)
+    return match.group(0).lower() if match else None
+
+
+def parse_format(fmt: str) -> str:
+    fmt = (fmt or "markdown").strip().lower()
+    if fmt not in VALID_FORMATS:
+        _fail(
+            "INVALID_FORMAT",
+            f"--format must be one of markdown|text|json (got: {fmt!r})",
+        )
+    return fmt
+
+
+# ---------------------------------------------------------------------------
+# HTTP
+# ---------------------------------------------------------------------------
+
+
+def _build_request(url: str, token: str | None, accept: str) -> urllib.request.Request:
+    req = urllib.request.Request(url, method="GET")
+    req.add_header("Accept", accept)
+    req.add_header("User-Agent", "openthread-plugin/export")
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    return req
+
+
+def _validate_scheme(url: str) -> None:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme == "https":
+        return
+    if parsed.scheme == "http":
+        host = (parsed.hostname or "").lower()
+        if host in ("localhost", "127.0.0.1", "::1"):
+            return
+        _fail(
+            "INSECURE_SCHEME",
+            f"Refusing plain-http fetch to non-loopback host: {host}",
+        )
+    _fail("HTTP_ERROR", f"Unsupported URL scheme: {parsed.scheme}")
+
+
+def _fetch(url: str, token: str | None, accept: str) -> tuple[bytes, dict[str, str]]:
+    """Fetch ``url`` returning (body, headers). Enforces the 5 MB cap.
+
+    Raises via ``_fail`` on any error so the caller never sees exceptions.
+    """
+    _validate_scheme(url)
+    req = _build_request(url, token, accept)
+    try:
+        ctx = ssl.create_default_context()
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT, context=ctx) as resp:
+            status = getattr(resp, "status", 200)
+            headers = {k.lower(): v for k, v in resp.headers.items()}
+            if status == 304:
+                # Should not happen since we don't send If-None-Match, but
+                # be defensive.
+                _fail("HTTP_ERROR", "Server returned 304 without a cached copy")
+            if status != 200:
+                _fail("HTTP_ERROR", f"Unexpected status {status}")
+            buf = bytearray()
+            while True:
+                chunk = resp.read(READ_CHUNK)
+                if not chunk:
+                    break
+                if len(buf) + len(chunk) > MAX_RESPONSE_BYTES:
+                    _fail(
+                        "SIZE_EXCEEDED",
+                        f"Response exceeded {MAX_RESPONSE_BYTES} bytes",
+                    )
+                buf.extend(chunk)
+            return bytes(buf), headers
+    except urllib.error.HTTPError as exc:  # type: ignore[attr-defined]
+        status = exc.code
+        headers = {k.lower(): v for k, v in (exc.headers or {}).items()}
+        if status == 403:
+            _fail("FORBIDDEN", "You don't have access to this community's exports")
+        if status == 404:
+            _fail("NOT_FOUND", "Post not found")
+        if status == 413:
+            _fail("TOO_LARGE", "Thread exceeds the maximum export size")
+        if status == 429:
+            retry = headers.get("retry-after", "")
+            _fail(
+                "RATE_LIMITED",
+                "Rate limited by server",
+                {"retryAfter": retry},
+            )
+        _fail("HTTP_ERROR", f"HTTP {status}")
+    except urllib.error.URLError as exc:
+        _fail("HTTP_ERROR", f"Network error: {exc.reason}")
+    except (TimeoutError, socket.timeout):
+        _fail("HTTP_ERROR", "Request timed out")
+    except (ssl.SSLError, OSError) as exc:
+        _fail("HTTP_ERROR", f"Connection error: {exc}")
+    # Unreachable — _fail exits — but keeps the type checker happy.
+    return b"", {}
+
+
+# ---------------------------------------------------------------------------
+# Metadata (title / author / community) fetch
+# ---------------------------------------------------------------------------
+
+
+def fetch_metadata(
+    api_base: str, uuid: str, token: str | None
+) -> dict[str, Any]:
+    """GET /api/posts/<uuid> for a lightweight title/author/community.
+
+    Returns a dict even on failure — missing fields fall back to
+    sensible placeholders so the export can still succeed on posts
+    whose metadata endpoint is unreachable.
+    """
+    url = f"{api_base.rstrip('/')}/api/posts/{uuid}"
+    try:
+        body, _ = _fetch(url, token, "application/json")
+    except SystemExit:
+        # _fetch already called _fail — we swallow it here because the
+        # metadata fetch is best-effort. If the main export call fails
+        # the user will see that error instead.
+        return {}
+    try:
+        parsed = json.loads(body.decode("utf-8", errors="replace"))
+    except (ValueError, UnicodeDecodeError):
+        return {}
+
+    # API envelope is typically `{"data": {...}}`.
+    data = parsed.get("data") if isinstance(parsed, dict) else None
+    if not isinstance(data, dict):
+        data = parsed if isinstance(parsed, dict) else {}
+
+    meta: dict[str, Any] = {}
+    meta["title"] = str(data.get("title") or "")
+    author = data.get("author")
+    if isinstance(author, dict):
+        meta["author"] = str(
+            author.get("username") or author.get("name") or ""
+        )
+    elif isinstance(author, str):
+        meta["author"] = author
+    else:
+        meta["author"] = ""
+    community = data.get("community")
+    if isinstance(community, dict):
+        meta["community"] = str(
+            community.get("slug") or community.get("name") or ""
+        )
+    elif isinstance(community, str):
+        meta["community"] = community
+    else:
+        meta["community"] = ""
+    return meta
+
+
+# ---------------------------------------------------------------------------
+# Slugification & filename
+# ---------------------------------------------------------------------------
+
+_SLUG_STRIP_RE = re.compile(r"[^\w\s-]", re.UNICODE)
+_SLUG_DASH_RE = re.compile(r"[-\s]+")
+
+
+def slugify(title: str, fallback: str = "thread") -> str:
+    """Lowercase, ASCII-ish, dash-separated slug capped at 40 chars."""
+    if not title:
+        return fallback
+    normalized = unicodedata.normalize("NFKD", title)
+    ascii_only = normalized.encode("ascii", "ignore").decode("ascii")
+    if not ascii_only.strip():
+        # Unicode-only title (e.g. CJK) — use word chars from the original.
+        ascii_only = _SLUG_STRIP_RE.sub("", normalized)
+    cleaned = _SLUG_STRIP_RE.sub("", ascii_only).strip().lower()
+    dashed = _SLUG_DASH_RE.sub("-", cleaned).strip("-")
+    if not dashed:
+        return fallback
+    return dashed[:40].strip("-") or fallback
+
+
+def default_filename(title: str, uuid: str, fmt: str) -> str:
+    slug = slugify(title)
+    short = uuid.split("-", 1)[0]
+    ext = FORMAT_EXT[fmt]
+    return f"ot-{slug}-{short}.{ext}"
+
+
+# ---------------------------------------------------------------------------
+# Path traversal guard
+# ---------------------------------------------------------------------------
+
+
+def resolve_output_path(
+    out_flag: str,
+    title: str,
+    uuid: str,
+    fmt: str,
+    cwd: pathlib.Path,
+) -> pathlib.Path:
+    """Return an absolute, safe output path. Aborts on traversal.
+
+    Rules:
+      * If ``out_flag`` is empty, use ``<cwd>/<default_filename>``.
+      * If ``out_flag`` is relative, resolve under ``cwd``. Reject if
+        the result escapes ``cwd``.
+      * If ``out_flag`` starts with ``~``, expand it. The result is
+        then treated as absolute.
+      * If ``out_flag`` is absolute, reject if it lives inside any
+        system denylist directory.
+      * If ``out_flag`` resolves to an existing directory, append the
+        default filename inside it.
+    """
+    if not out_flag:
+        return cwd / default_filename(title, uuid, fmt)
+
+    # Reject NUL bytes up front — they'd corrupt any subsequent
+    # filesystem syscall.
+    if "\x00" in out_flag:
+        _fail("UNSAFE_PATH", "Output path contains NUL byte")
+
+    expanded = os.path.expanduser(out_flag)
+    candidate = pathlib.Path(expanded)
+
+    if not candidate.is_absolute():
+        # Relative: resolve under cwd and ensure it stays under cwd.
+        joined = (cwd / candidate).resolve()
+        try:
+            joined.relative_to(cwd.resolve())
+        except ValueError:
+            _fail(
+                "UNSAFE_PATH",
+                f"Relative --out escapes current working directory: {out_flag}",
+            )
+        candidate = joined
+    else:
+        # Check BOTH the raw path and the realpath-resolved one, because
+        # macOS silently resolves ``/etc`` -> ``/private/etc`` and we
+        # want to reject both forms. We also strip a leading ``/private``
+        # prefix before comparing so a user-supplied ``/private/etc/…``
+        # is caught too.
+        raw_candidate = pathlib.Path(expanded)
+        resolved = candidate.resolve()
+
+        def _is_denylisted(p: pathlib.Path) -> str | None:
+            s = str(p)
+            # macOS realpath prefix.
+            variants = [s]
+            if s.startswith("/private/"):
+                variants.append(s[len("/private") :])
+            for v in variants:
+                for bad in SYSTEM_DENYLIST:
+                    bad_rstrip = bad.rstrip("/")
+                    if v == bad_rstrip or v.startswith(bad):
+                        return bad
+            return None
+
+        hit = _is_denylisted(raw_candidate) or _is_denylisted(resolved)
+        if hit:
+            _fail(
+                "UNSAFE_PATH",
+                f"Refusing to write into system directory: {hit}",
+            )
+        candidate = resolved
+
+    # If the resolved path is an existing directory, drop the default
+    # filename inside it.
+    if candidate.exists() and candidate.is_dir():
+        candidate = candidate / default_filename(title, uuid, fmt)
+
+    return candidate
+
+
+# ---------------------------------------------------------------------------
+# Banner construction
+# ---------------------------------------------------------------------------
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def build_markdown_banner(
+    uuid: str,
+    author: str,
+    community: str,
+    fmt: str,
+    source_url: str,
+) -> str:
+    return (
+        "<!--\n"
+        "Exported from OpenThread\n"
+        f"post:      {uuid}\n"
+        f"author:    @{author or 'unknown'}\n"
+        f"community: c/{community or 'unknown'}\n"
+        f"fetched:   {_now_iso()}\n"
+        f"format:    {fmt}\n"
+        f"source:    {source_url}\n"
+        "\n"
+        "This content was masked at ingest on OpenThread and re-masked\n"
+        "locally before being written to this file. Review before\n"
+        "publishing elsewhere.\n"
+        "-->\n\n"
+    )
+
+
+def build_text_banner(
+    uuid: str,
+    author: str,
+    community: str,
+    fmt: str,
+) -> str:
+    bar = "=" * 60
+    return (
+        f"{bar}\n"
+        "Exported from OpenThread\n"
+        f"post:      {uuid}\n"
+        f"author:    @{author or 'unknown'}\n"
+        f"community: c/{community or 'unknown'}\n"
+        f"fetched:   {_now_iso()}\n"
+        f"format:    {fmt}\n"
+        f"{bar}\n\n"
+    )
+
+
+def wrap_json_banner(
+    data: Any,
+    uuid: str,
+    author: str,
+    community: str,
+) -> dict[str, Any]:
+    return {
+        "_meta": {
+            "source": "openthread",
+            "post": uuid,
+            "author": author or "unknown",
+            "community": community or "unknown",
+            "fetched": _now_iso(),
+            "maskedLocally": True,
+            "notice": (
+                "Masked at ingest and re-masked locally. "
+                "Review before publishing."
+            ),
+        },
+        "data": data,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Post-processing
+# ---------------------------------------------------------------------------
+
+
+def _local_mask_text(body: str) -> str:
+    home = str(pathlib.Path.home())
+    body = sanitize_mod.strip_controls(body)
+    return mask_mod.mask(body, home=home)
+
+
+def _mask_json_strings(value: Any) -> Any:
+    """Walk a parsed JSON document and mask every string leaf."""
+    home = str(pathlib.Path.home())
+    if isinstance(value, str):
+        return mask_mod.mask(sanitize_mod.strip_controls(value), home=home)
+    if isinstance(value, list):
+        return [_mask_json_strings(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _mask_json_strings(v) for k, v in value.items()}
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Atomic write
+# ---------------------------------------------------------------------------
+
+
+def atomic_write(path: pathlib.Path, data: bytes, overwrite: bool) -> None:
+    """Write ``data`` to ``path`` via a ``.part`` rename. Mode 0644."""
+    if path.exists() and not overwrite:
+        _fail(
+            "EXISTS",
+            f"Target file already exists: {path}",
+            {"path": str(path)},
+        )
+    parent = path.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    # tempfile.NamedTemporaryFile lets us control the directory so the
+    # rename stays on the same filesystem (atomic).
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=path.name + ".",
+        suffix=".part",
+        dir=str(parent),
+    )
+    tmp_path = pathlib.Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+            fh.flush()
+            try:
+                os.fsync(fh.fileno())
+            except OSError:
+                # fsync may not be supported on some filesystems — best effort.
+                pass
+        os.chmod(tmp_path, 0o644)
+        os.replace(tmp_path, path)
+    except Exception:
+        try:
+            tmp_path.unlink()
+        except OSError:
+            pass
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    api_base = os.environ.get("API_BASE", "https://openthread.me")
+    raw_input = os.environ.get("INPUT", "")
+    fmt = parse_format(os.environ.get("FORMAT", "markdown"))
+    out_flag = os.environ.get("OUT", "") or ""
+    use_stdout = os.environ.get("STDOUT", "0") == "1"
+    no_banner = os.environ.get("NO_BANNER", "0") == "1"
+    token = os.environ.get("TOKEN", "") or None
+    overwrite = os.environ.get("OVERWRITE", "0") == "1"
+
+    uuid = extract_uuid(raw_input)
+    if not uuid:
+        _fail("INVALID_UUID", f"Could not extract UUID from input: {raw_input!r}")
+
+    # Step 1: metadata for title/author/community. Best effort.
+    meta = fetch_metadata(api_base, uuid, token)
+
+    # Step 2: actual export.
+    export_url = (
+        f"{api_base.rstrip('/')}/api/posts/{uuid}/export?format={fmt}"
+    )
+    accept_header = {
+        "markdown": "text/markdown",
+        "text": "text/plain",
+        "json": "application/json",
+    }[fmt]
+    raw_body, _headers = _fetch(export_url, token, accept_header)
+
+    # Step 3: decode + defense-in-depth mask.
+    if fmt == "json":
+        try:
+            parsed = json.loads(raw_body.decode("utf-8", errors="replace"))
+        except ValueError as exc:
+            _fail("HTTP_ERROR", f"Response was not valid JSON: {exc}")
+        masked_json = _mask_json_strings(parsed)
+        # Use the server's title if we didn't get one from metadata.
+        if not meta.get("title") and isinstance(parsed, dict):
+            server_title = parsed.get("title")
+            if isinstance(server_title, str):
+                meta["title"] = server_title
+        if no_banner:
+            out_obj: Any = masked_json
+        else:
+            out_obj = wrap_json_banner(
+                masked_json,
+                uuid,
+                meta.get("author", ""),
+                meta.get("community", ""),
+            )
+        body_bytes = json.dumps(
+            out_obj, indent=2, ensure_ascii=False
+        ).encode("utf-8") + b"\n"
+    else:
+        text_body = raw_body.decode("utf-8", errors="replace")
+        masked_text = _local_mask_text(text_body)
+        if not meta.get("title"):
+            # Try to fish a title out of the first heading or line.
+            first_line = masked_text.lstrip().splitlines()[0] if masked_text.strip() else ""
+            meta["title"] = first_line.lstrip("# ").strip()
+        if no_banner:
+            final_text = masked_text
+        elif fmt == "markdown":
+            banner = build_markdown_banner(
+                uuid,
+                meta.get("author", ""),
+                meta.get("community", ""),
+                fmt,
+                export_url,
+            )
+            final_text = banner + masked_text
+        else:  # text
+            banner = build_text_banner(
+                uuid,
+                meta.get("author", ""),
+                meta.get("community", ""),
+                fmt,
+            )
+            final_text = banner + masked_text
+        body_bytes = final_text.encode("utf-8")
+
+    if len(body_bytes) > MAX_RESPONSE_BYTES:
+        _fail(
+            "SIZE_EXCEEDED",
+            f"Rendered body exceeded {MAX_RESPONSE_BYTES} bytes",
+        )
+
+    title = meta.get("title") or "thread"
+
+    # Step 4: stdout mode writes body to stdout, metadata to stderr.
+    if use_stdout:
+        try:
+            sys.stdout.buffer.write(body_bytes)
+            sys.stdout.flush()
+        except BrokenPipeError:
+            pass
+        summary = {
+            "path": None,
+            "bytes": len(body_bytes),
+            "uuid": uuid,
+            "format": fmt,
+            "title": title,
+        }
+        sys.stderr.write(json.dumps(summary) + "\n")
+        sys.stderr.flush()
+        return
+
+    # Step 5: resolve the target path and write atomically.
+    cwd = pathlib.Path(os.getcwd()).resolve()
+    target = resolve_output_path(out_flag, title, uuid, fmt, cwd)
+
+    atomic_write(target, body_bytes, overwrite=overwrite)
+
+    summary = {
+        "path": str(target),
+        "bytes": len(body_bytes),
+        "uuid": uuid,
+        "format": fmt,
+        "title": title,
+    }
+    sys.stdout.write(json.dumps(summary) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        _emit_error("INTERRUPTED", "Interrupted by user")
+        sys.exit(130)
+    except Exception as exc:  # pragma: no cover - last-chance safety net
+        _emit_error("INTERNAL_ERROR", f"{type(exc).__name__}: {exc}")
+        sys.exit(1)