qhost 0.1.0__tar.gz

qhost-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Fasnacht
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

qhost-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: qhost
+Version: 0.1.0
+Summary: Self-hosted static-site host with a single trusted publisher.
+Author: Jan Fasnacht
+License: MIT
+Project-URL: Homepage, https://github.com/janfasnacht/qhost
+Project-URL: Source, https://github.com/janfasnacht/qhost
+Project-URL: Issues, https://github.com/janfasnacht/qhost/issues
+Project-URL: Changelog, https://github.com/janfasnacht/qhost/blob/main/CHANGELOG.md
+Keywords: static-site,self-hosted,file-sharing,expiring-shares,preview-environments
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: System :: Archiving :: Mirroring
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Provides-Extra: server
+Requires-Dist: fastapi>=0.111; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
+Requires-Dist: bcrypt>=4.1; extra == "server"
+Requires-Dist: python-multipart>=0.0.9; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: asgi-lifespan>=2.1; extra == "dev"
+Dynamic: license-file
+
+# qhost
+
+qhost publishes a directory of static files — a built site, a rendered
+report, a coverage tree — at a URL that requires access and expires on a
+schedule. The operator runs one container, points a DNS record at their
+own reverse proxy, and manages shares from the command line. It is
+access-controlled hosting for a single trusted publisher per instance;
+it does not isolate mutually distrusting shares from one another.
+
+## Self-host the server
+
+qhostd ships as `ghcr.io/janfasnacht/qhost-server`. Drop a
+`docker-compose.yml` and `.env` somewhere on your box and start it:
+
+```yaml
+# docker-compose.yml
+services:
+  qhostd:
+    image: ghcr.io/janfasnacht/qhost-server:0.1.0
+    restart: unless-stopped
+    environment:
+      QHOST_DOMAIN: ${QHOST_DOMAIN:?}
+      QHOST_TRUSTED_PROXY: ${QHOST_TRUSTED_PROXY:?}
+      QHOST_TOKEN: ${QHOST_TOKEN:-}
+    volumes:
+      - qhost_data:/data
+    ports:
+      - "127.0.0.1:8000:8000"
+
+volumes:
+  qhost_data:
+```
+
+```
+# .env
+QHOST_DOMAIN=share.example.com
+QHOST_TRUSTED_PROXY=127.0.0.1   # whatever IP / CIDR your proxy connects from
+QHOST_TOKEN=                    # leave blank to auto-generate on first start
+```
+
+```bash
+docker compose up -d
+docker compose exec qhostd cat /data/operator-token   # if you left it blank
+```
+
+qhostd is now on `http://127.0.0.1:8000` of the host, ready to be
+proxied. The full env-var surface is in
+[`deploy/.env.example`](deploy/.env.example) and the canonical compose
+is in [`deploy/docker-compose.yml`](deploy/docker-compose.yml).
+
+## Wire a reverse proxy
+
+qhostd doesn't terminate TLS, doesn't strip incoming `X-Forwarded-For`,
+and doesn't enforce a body-size cap before the request reaches Python.
+A proxy in front of it has to do those three things, and qhostd has to
+trust that proxy via `QHOST_TRUSTED_PROXY` (an IP or CIDR — see above).
+
+Full ready-to-edit examples are in [`deploy/proxies/`](deploy/proxies/).
+The interesting line in each:
+
+**Caddy** ([`deploy/proxies/Caddyfile`](deploy/proxies/Caddyfile))
+
+```caddyfile
+{$QHOST_DOMAIN} {
+    reverse_proxy 127.0.0.1:8000 {
+        header_up X-Forwarded-For {http.request.remote.host}   # overwrite, not append
+    }
+    request_body { max_size 110MB }
+    header Strict-Transport-Security "max-age=31536000; includeSubDomains"
+}
+```
+
+**nginx** ([`deploy/proxies/nginx.conf`](deploy/proxies/nginx.conf))
+
+```nginx
+proxy_set_header X-Forwarded-For $remote_addr;   # overwrite, not append
+client_max_body_size 110m;
+```
+
+**Cloudflare Tunnel** ([`deploy/proxies/cloudflared.md`](deploy/proxies/cloudflared.md))
+
+```yaml
+ingress:
+  - hostname: share.example.com
+    service: http://127.0.0.1:8000
+```
+
+`cloudflared` connects from loopback, so `QHOST_TRUSTED_PROXY=127.0.0.1`
+is what you want.
+
+## Install the CLI
+
+```bash
+pip install qhost
+qhost login https://share.example.com
+```
+
+`qhost login` prompts for the operator token and writes it to
+`~/.config/qhost/config.toml` (mode 0600).
+
+## Publish
+
+```bash
+cd path/to/built/site && qhost publish
+```
+
+`qhost publish` from a directory containing `index.html` publishes that
+directory as-is. From a Quarto project (`_quarto.yml` present) it runs
+`quarto render` first. Otherwise it refuses; pass `--dir <path>` to
+point at a built output or `--build <name>` to force a specific builder.
+
+`qhost --help` covers the rest: `publish`, `ls`, `info`, `extend`, `rm`,
+`open`, `doctor`. Default expiry is seven days. `--password` gates a
+share behind HTTP Basic with a generated password; `--public` makes a
+guessable URL with no secret; the default `link` mode treats the URL
+itself as the credential — `/s/<slug>/` carries ~80 bits of entropy and
+is not enumerable.
+
+`qhost publish --sandbox` serves a share under
+`Content-Security-Policy: sandbox allow-scripts`, the only
+intra-instance isolation primitive. `qhost doctor` flags content that
+probably wants it.
+
+## Trust model
+
+One operator token authorizes all publishing on an instance; every
+visitor is untrusted. All shares serve from the same browser origin, so
+a share's JavaScript can reach any other share on the same instance
+with the visitor's ambient Basic-auth credentials. For mutually
+distrusting publishers, run separate instances on separate origins.
+
+---
+
+Configuration: [`deploy/.env.example`](deploy/.env.example). Reverse
+proxy examples: [`deploy/proxies/`](deploy/proxies/). Vulnerability
+reports: [`SECURITY.md`](SECURITY.md). MIT.

qhost-0.1.0/README.md

@@ -0,0 +1,136 @@
+# qhost
+
+qhost publishes a directory of static files — a built site, a rendered
+report, a coverage tree — at a URL that requires access and expires on a
+schedule. The operator runs one container, points a DNS record at their
+own reverse proxy, and manages shares from the command line. It is
+access-controlled hosting for a single trusted publisher per instance;
+it does not isolate mutually distrusting shares from one another.
+
+## Self-host the server
+
+qhostd ships as `ghcr.io/janfasnacht/qhost-server`. Drop a
+`docker-compose.yml` and `.env` somewhere on your box and start it:
+
+```yaml
+# docker-compose.yml
+services:
+  qhostd:
+    image: ghcr.io/janfasnacht/qhost-server:0.1.0
+    restart: unless-stopped
+    environment:
+      QHOST_DOMAIN: ${QHOST_DOMAIN:?}
+      QHOST_TRUSTED_PROXY: ${QHOST_TRUSTED_PROXY:?}
+      QHOST_TOKEN: ${QHOST_TOKEN:-}
+    volumes:
+      - qhost_data:/data
+    ports:
+      - "127.0.0.1:8000:8000"
+
+volumes:
+  qhost_data:
+```
+
+```
+# .env
+QHOST_DOMAIN=share.example.com
+QHOST_TRUSTED_PROXY=127.0.0.1   # whatever IP / CIDR your proxy connects from
+QHOST_TOKEN=                    # leave blank to auto-generate on first start
+```
+
+```bash
+docker compose up -d
+docker compose exec qhostd cat /data/operator-token   # if you left it blank
+```
+
+qhostd is now on `http://127.0.0.1:8000` of the host, ready to be
+proxied. The full env-var surface is in
+[`deploy/.env.example`](deploy/.env.example) and the canonical compose
+is in [`deploy/docker-compose.yml`](deploy/docker-compose.yml).
+
+## Wire a reverse proxy
+
+qhostd doesn't terminate TLS, doesn't strip incoming `X-Forwarded-For`,
+and doesn't enforce a body-size cap before the request reaches Python.
+A proxy in front of it has to do those three things, and qhostd has to
+trust that proxy via `QHOST_TRUSTED_PROXY` (an IP or CIDR — see above).
+
+Full ready-to-edit examples are in [`deploy/proxies/`](deploy/proxies/).
+The interesting line in each:
+
+**Caddy** ([`deploy/proxies/Caddyfile`](deploy/proxies/Caddyfile))
+
+```caddyfile
+{$QHOST_DOMAIN} {
+    reverse_proxy 127.0.0.1:8000 {
+        header_up X-Forwarded-For {http.request.remote.host}   # overwrite, not append
+    }
+    request_body { max_size 110MB }
+    header Strict-Transport-Security "max-age=31536000; includeSubDomains"
+}
+```
+
+**nginx** ([`deploy/proxies/nginx.conf`](deploy/proxies/nginx.conf))
+
+```nginx
+proxy_set_header X-Forwarded-For $remote_addr;   # overwrite, not append
+client_max_body_size 110m;
+```
+
+**Cloudflare Tunnel** ([`deploy/proxies/cloudflared.md`](deploy/proxies/cloudflared.md))
+
+```yaml
+ingress:
+  - hostname: share.example.com
+    service: http://127.0.0.1:8000
+```
+
+`cloudflared` connects from loopback, so `QHOST_TRUSTED_PROXY=127.0.0.1`
+is what you want.
+
+## Install the CLI
+
+```bash
+pip install qhost
+qhost login https://share.example.com
+```
+
+`qhost login` prompts for the operator token and writes it to
+`~/.config/qhost/config.toml` (mode 0600).
+
+## Publish
+
+```bash
+cd path/to/built/site && qhost publish
+```
+
+`qhost publish` from a directory containing `index.html` publishes that
+directory as-is. From a Quarto project (`_quarto.yml` present) it runs
+`quarto render` first. Otherwise it refuses; pass `--dir <path>` to
+point at a built output or `--build <name>` to force a specific builder.
+
+`qhost --help` covers the rest: `publish`, `ls`, `info`, `extend`, `rm`,
+`open`, `doctor`. Default expiry is seven days. `--password` gates a
+share behind HTTP Basic with a generated password; `--public` makes a
+guessable URL with no secret; the default `link` mode treats the URL
+itself as the credential — `/s/<slug>/` carries ~80 bits of entropy and
+is not enumerable.
+
+`qhost publish --sandbox` serves a share under
+`Content-Security-Policy: sandbox allow-scripts`, the only
+intra-instance isolation primitive. `qhost doctor` flags content that
+probably wants it.
+
+## Trust model
+
+One operator token authorizes all publishing on an instance; every
+visitor is untrusted. All shares serve from the same browser origin, so
+a share's JavaScript can reach any other share on the same instance
+with the visitor's ambient Basic-auth credentials. For mutually
+distrusting publishers, run separate instances on separate origins.
+
+---
+
+Configuration: [`deploy/.env.example`](deploy/.env.example). Reverse
+proxy examples: [`deploy/proxies/`](deploy/proxies/). Vulnerability
+reports: [`SECURITY.md`](SECURITY.md). MIT.

qhost-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qhost"
+version = "0.1.0"
+description = "Self-hosted static-site host with a single trusted publisher."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "Jan Fasnacht" }]
+keywords = [
+    "static-site",
+    "self-hosted",
+    "file-sharing",
+    "expiring-shares",
+    "preview-environments",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+    "Topic :: System :: Archiving :: Mirroring",
+]
+dependencies = [
+    "pydantic>=2.6",
+    "httpx>=0.27",
+    "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/janfasnacht/qhost"
+Source = "https://github.com/janfasnacht/qhost"
+Issues = "https://github.com/janfasnacht/qhost/issues"
+Changelog = "https://github.com/janfasnacht/qhost/blob/main/CHANGELOG.md"
+
+[project.scripts]
+qhost = "qhost.cli:app"
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.111",
+    "uvicorn[standard]>=0.30",
+    "bcrypt>=4.1",
+    "python-multipart>=0.0.9",
+]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6",
+    "ruff>=0.5",
+    "asgi-lifespan>=2.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["qhost_core*", "qhost*", "qhostd*"]
+exclude = ["tests*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+asyncio_mode = "auto"

qhost-0.1.0/qhost/__init__.py

@@ -0,0 +1,3 @@
+from qhost_core.version import __version__
+
+__all__ = ["__version__"]

qhost-0.1.0/qhost/_io.py

@@ -0,0 +1,66 @@
+"""Shared filesystem helpers for the three local-state modules.
+
+Atomic writes (tmp + chmod + replace) and mode-checks are identical for
+`config.toml`, `credentials.toml`, and `.qhost`, so they live here. Each
+state module imports from this — nothing else does.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+_MODE_WARNED: set[str] = set()
+
+
+def atomic_write(path: Path, payload: str, *, mode: int) -> None:
+    """Write `payload` to `path` via tmp + chmod + replace.
+
+    Mode is set on the tmp file *before* the rename so the visible file is
+    never briefly readable in a wider mode. Skips chmod on Windows.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=path.name + ".",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+        if not sys.platform.startswith("win"):
+            os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise
+
+
+def warn_if_world_readable(path: Path) -> None:
+    """Print a one-time stderr warning if `path` is readable by group/other.
+
+    Used for secrets files (`config.toml`, `credentials.toml`). No-op on
+    Windows. Each path is warned about at most once per process to avoid
+    spamming CLI output across multiple commands in the same invocation.
+    """
+    if sys.platform.startswith("win"):
+        return
+    key = str(path)
+    if key in _MODE_WARNED:
+        return
+    try:
+        mode = path.stat().st_mode & 0o777
+    except OSError:
+        return
+    if mode & 0o077:
+        _MODE_WARNED.add(key)
+        print(
+            f"warning: {path} mode is {oct(mode)} (should be 0o600); "
+            "anyone on this machine can read it.",
+            file=sys.stderr,
+        )

qhost-0.1.0/qhost/_toml.py

@@ -0,0 +1,99 @@
+"""Minimal TOML writer for qhost's three state files.
+
+Reads use stdlib `tomllib` (Python 3.11+). Writing TOML is implemented in-tree
+to avoid pulling in a runtime dep (`tomli_w`) just to emit a few dozen lines.
+
+The subset supported is deliberately narrow:
+- Top-level scalar `key = value` lines.
+- Section headers `[a]`, `[a.b]`, `[a."quoted"."key"]`.
+- String, int, and bool scalars.
+
+Anything else (arrays, dates, multi-line strings, inline tables, floats)
+raises `TypeError`. If a future state file needs more, extend here — not at
+the call site.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+_BARE_KEY = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def dumps(data: Mapping[str, Any]) -> str:
+    """Render a nested mapping to TOML text."""
+    lines: list[str] = []
+    scalars, subs = _split(data)
+    for k, v in scalars:
+        lines.append(_format_kv(k, v))
+    for k, v in subs:
+        if lines:
+            lines.append("")
+        _emit_section(lines, [k], v)
+    text = "\n".join(lines)
+    return text + "\n" if text else ""
+
+
+def _emit_section(lines: list[str], path: list[str], data: Mapping[str, Any]) -> None:
+    scalars, subs = _split(data)
+    # Emit a header for this path when it has scalars of its own or is a leaf;
+    # otherwise the path is purely a parent and its header is implicit.
+    if scalars or not subs:
+        lines.append(f"[{_format_path(path)}]")
+        for k, v in scalars:
+            lines.append(_format_kv(k, v))
+    for k, v in subs:
+        lines.append("")
+        _emit_section(lines, [*path, k], v)
+
+
+def _split(
+    data: Mapping[str, Any],
+) -> tuple[list[tuple[str, Any]], list[tuple[str, Mapping[str, Any]]]]:
+    scalars: list[tuple[str, Any]] = []
+    subs: list[tuple[str, Mapping[str, Any]]] = []
+    for k, v in data.items():
+        if isinstance(v, Mapping):
+            subs.append((k, v))
+        else:
+            scalars.append((k, v))
+    return scalars, subs
+
+
+def _format_path(path: list[str]) -> str:
+    return ".".join(_format_key(p) for p in path)
+
+
+def _format_key(k: str) -> str:
+    if _BARE_KEY.fullmatch(k):
+        return k
+    return _quote_string(k)
+
+
+def _format_kv(k: str, v: Any) -> str:
+    return f"{_format_key(k)} = {_format_value(v)}"
+
+
+def _format_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, str):
+        return _quote_string(v)
+    raise TypeError(f"unsupported TOML value type: {type(v).__name__}")
+
+
+def _quote_string(s: str) -> str:
+    escaped = (
+        s.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\b", "\\b")
+        .replace("\t", "\\t")
+        .replace("\n", "\\n")
+        .replace("\f", "\\f")
+        .replace("\r", "\\r")
+    )
+    return f'"{escaped}"'