zettcode-gateway 0.4.0__tar.gz → 0.4.2__tar.gz

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/.gitignore

@@ -35,3 +35,8 @@ docs/internal/palettes.html
 
 # The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
 packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-gateway
-Version: 0.4.0
+Version: 0.4.2
 Summary: The web gateway of ZettCode: the chat page and the graph over a running server
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: starlette<2,>=0.48
+Requires-Dist: starlette<2,>=0.51
 Requires-Dist: uvicorn<1,>=0.35
 Requires-Dist: zettcode-engine
 Requires-Dist: zettcode-sdk

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
 dependencies = [
   "zettcode-engine",
   "zettcode-sdk",
-  "starlette>=0.48,<2",
+  "starlette>=0.51,<2",
   "uvicorn>=0.35,<1",
 ]
 

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/src/zettcode/gateway/app.py

@@ -12,6 +12,8 @@ carry the gateway's own.
 from __future__ import annotations
 
 import asyncio
+import base64
+import binascii
 import contextlib
 import hmac
 import json
@@ -29,6 +31,7 @@ from urllib.parse import urlsplit
 
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
 from starlette.requests import HTTPConnection, Request
 from starlette.responses import FileResponse, JSONResponse, PlainTextResponse, Response
 from starlette.routing import Mount, Route, WebSocketRoute
@@ -70,6 +73,12 @@ LOGIN_WINDOW = 600.0
 #: What a WebSocket is closed with when it is not signed in.
 UNAUTHORIZED = 4401
 
+#: The subprotocol a native client asks for, and the prefix under which it offers its token. A browser cannot put an
+#: ``Authorization`` header on a WebSocket, so the token goes beside the subprotocol, base64url-encoded: a protocol
+#: name is a token and base64url is made of token characters.
+WS_PROTOCOL = "zettcode"
+WS_TOKEN_PREFIX = "zettcode.token."
+
 #: The names a browser on this machine reaches it by.
 LOOPBACK_NAMES = frozenset({"127.0.0.1", "::1", "localhost"})
 
@@ -149,19 +158,43 @@ class Auth:
         return scheme.lower() == "bearer" and self.token_ok(given.strip())
 
 
-def same_origin(connection: HTTPConnection, *, required: bool = False) -> bool:
+def same_origin(connection: HTTPConnection, *, required: bool = False, allowed: tuple[str, ...] = ()) -> bool:
     """Return whether a request did not come from another site: it names this host in ``Origin``.
 
     A request with no ``Origin`` is let through unless ``required``: a browser sends one on every write and every socket,
     and with no token (nothing but this check stands between a page on another site and a gateway that runs commands) a
     program that writes to the gateway says where it is from too.
+
+    ``allowed`` names the origins of a native client (see :attr:`Settings.allowed_origins`); they are let through as
+    the gateway's own, and every request from them still has to carry the token.
     """
     origin = connection.headers.get("origin")
     if not origin:
         return not required
+    if origin in allowed:
+        return True
     return urlsplit(origin).netloc == connection.headers.get("host", "")
 
 
+def offered(connection: HTTPConnection) -> list[str]:
+    """Return the WebSocket subprotocols the client offered, trimmed."""
+    header = connection.headers.get("sec-websocket-protocol", "")
+    return [item.strip() for item in header.split(",") if item.strip()]
+
+
+def websocket_token(connection: HTTPConnection) -> str:
+    """Return the token a native client offered as a subprotocol, or ``""`` when it offered none it can be read from."""
+    for protocol in offered(connection):
+        if not protocol.startswith(WS_TOKEN_PREFIX):
+            continue
+        encoded = protocol[len(WS_TOKEN_PREFIX) :]
+        try:
+            return base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)).decode()
+        except (binascii.Error, UnicodeDecodeError, ValueError):
+            return ""
+    return ""
+
+
 class Headers:
     """ASGI middleware that puts the response headers every answer of the gateway carries on it."""
 
@@ -205,6 +238,7 @@ Handler = Callable[[Request], Awaitable[Any]]
 def create_app(settings: Settings, backend: Backend | None = None, *, static: Path = STATIC) -> Starlette:
     """Return the application for these settings; a test gives a backend of its own, and the folder the page is in."""
     auth = Auth(settings.token)
+    allowed = settings.allowed_origins
     gateway = Gateway(backend if backend is not None else SdkBackend(settings.workspace, settings.directory), settings)
 
     @asynccontextmanager
@@ -235,7 +269,9 @@ def create_app(settings: Settings, backend: Backend | None = None, *, static: Pa
             try:
                 if not public and not auth.allowed(request):
                     raise GatewayError(401, "unauthorized", "Sign in first")
-                if request.method not in ("GET", "HEAD") and not same_origin(request, required=auth.open):
+                if request.method not in ("GET", "HEAD") and not same_origin(
+                    request, required=auth.open, allowed=allowed
+                ):
                     raise GatewayError(403, "forbidden", "This request came from another site")
                 result = await handler(request)
                 return result if isinstance(result, Response) else JSONResponse(result)
@@ -394,10 +430,19 @@ def create_app(settings: Settings, backend: Backend | None = None, *, static: Pa
 
     # -- the event socket -------------------------------------------------------------------------
     async def events(websocket: WebSocket) -> None:
-        if not auth.allowed(websocket) or not same_origin(websocket, required=auth.open):
+        protocols = offered(websocket)
+        subprotocol = WS_PROTOCOL if WS_PROTOCOL in protocols else None
+        if not (auth.allowed(websocket) or auth.token_ok(websocket_token(websocket))) or not same_origin(
+            websocket, required=auth.open, allowed=allowed
+        ):
+            # Accept first: a close before the handshake is an HTTP refusal, which a browser reports as 1006, and the
+            # page could not tell a refused token from a dropped network. Echo the offered subprotocol as well: a
+            # browser that negotiated one refuses a handshake that comes back without it.
+            await websocket.accept(subprotocol=subprotocol)
             await websocket.close(UNAUTHORIZED)
             return
-        await websocket.accept()
+        # A native client offers ``zettcode`` beside its token; echo it, or the browser would refuse the socket.
+        await websocket.accept(subprotocol=subprotocol)
         queue = gateway.subscribe()
 
         async def pump() -> None:
@@ -441,6 +486,7 @@ def create_app(settings: Settings, backend: Backend | None = None, *, static: Pa
         Route("/api/threads/{id}/recheck", api(recheck), methods=["POST"]),
         Route("/api/threads/{id}/send", api(send), methods=["POST"]),
         Route("/api/threads/{id}/pictures/{picture}", api(picture)),
+        Route("/api/groups/{name}/send", api(send_group), methods=["POST"]),
         Route("/api/daemons", api(spawn), methods=["POST"]),
         Route("/api/daemons/{id}", api(delete), methods=["DELETE"]),
         Route("/api/daemons/{id}/stop", api(stop), methods=["POST"]),
@@ -448,7 +494,25 @@ def create_app(settings: Settings, backend: Backend | None = None, *, static: Pa
         WebSocketRoute("/api/events", events),
         Mount("/static", Files(directory=static, check_dir=False), name="static"),
     ]
-    app = Starlette(routes=routes, lifespan=lifespan, middleware=[Middleware(Headers)])
+    app = Starlette(
+        routes=routes,
+        lifespan=lifespan,
+        middleware=[
+            # Outermost, so a refusal from the routes below still carries the headers a native client's browser
+            # needs to read it, and a preflight is answered before it can be mistaken for a write that needs the token.
+            Middleware(
+                CORSMiddleware,
+                allow_origins=list(allowed),
+                allow_methods=["GET", "HEAD", "POST", "PATCH", "DELETE", "OPTIONS"],
+                allow_headers=["authorization", "content-type"],
+                # The desktop page, or an operator's --client-origin page, can be reached over a private network;
+                # the allowlist is what keeps a public page out, and the token is still required.
+                allow_private_network=True,
+                max_age=600,
+            ),
+            Middleware(Headers),
+        ],
+    )
     app.state.gateway = gateway
     app.state.auth = auth
     return app

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/src/zettcode/gateway/cli.py

@@ -27,6 +27,7 @@ import sys
 import time
 from pathlib import Path
 from typing import Any, Literal
+from urllib.parse import urlsplit
 
 from zettcode import logging_setup
 from zettcode.processes import command_line, is_module_command, still_there
@@ -56,6 +57,40 @@ EXIT_OK = 0
 EXIT_FAILED = 1
 
 
+def origin(value: str) -> str:
+    """Return ``value`` as an origin, or stop: a scheme and a host, and nothing after a port.
+
+    A browser sends ``Origin`` as ``scheme://host[:port]`` and never with a trailing slash, so a flag that accepts one
+    would never match anything. Only schemes a page or a native shell can run under are accepted: ``ws://`` is a
+    socket, not an origin a browser ever sends.
+    """
+    text = value.strip().rstrip("/")
+    parts = urlsplit(text)
+    try:
+        port = parts.port
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not an origin: {value!r} (the port is out of range)") from None
+    scheme = parts.scheme.lower()
+    host = parts.hostname
+    if (
+        scheme not in ("http", "https", "app")
+        or not host
+        or parts.path
+        or parts.query
+        or parts.fragment
+        or "@" in parts.netloc
+        or parts.netloc.endswith(":")
+        or (port is not None and not 0 < port < 65536)
+    ):
+        raise argparse.ArgumentTypeError(f"not an origin: {value!r} (write scheme://host[:port])")
+    # A browser omits a scheme's default port; strip it here or the flag would never match.
+    if port is None or (scheme == "http" and port == 80) or (scheme == "https" and port == 443):
+        authority = f"[{host}]" if ":" in host else host
+    else:
+        authority = f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
+    return f"{scheme}://{authority}"
+
+
 def build_parser() -> argparse.ArgumentParser:
     """Return the parser: the action, where to listen, who may sign in, and where agents may be started."""
     parser = argparse.ArgumentParser(
@@ -112,6 +147,17 @@ def build_parser() -> argparse.ArgumentParser:
         default=argparse.SUPPRESS,
         help="let the page start daemons with the full shell level again, undoing a recorded --no-full",
     )
+    parser.add_argument(
+        "--client-origin",
+        metavar="ORIGIN",
+        action="append",
+        type=origin,
+        default=argparse.SUPPRESS,
+        help=(
+            "let a page served from this origin call the gateway, on top of the built-in native client origins "
+            "(repeatable; needs a token). An origin is scheme://host[:port], without a path"
+        ),
+    )
     parser.add_argument(
         "--directory",
         metavar="DIR",
@@ -171,6 +217,11 @@ def settings_from(argv: list[str] | None = None, *, base: Settings | None = None
     else:
         directory = base.directory if base is not None else default_directory()
     log_level = getattr(args, "log_level", None) or (base.log_level if base is not None else "info")
+    origins_given = getattr(args, "client_origin", None)
+    if origins_given is None:
+        client_origins = base.client_origins if base is not None else ()
+    else:
+        client_origins = tuple(dict.fromkeys(origins_given))
 
     if not 0 < port < 65536:
         raise SystemExit(f"zettcode gateway: --port must be between 1 and 65535, not {port}")
@@ -182,6 +233,10 @@ def settings_from(argv: list[str] | None = None, *, base: Settings | None = None
             f"zettcode gateway: listening on {host} needs a token (--token or ${TOKEN_VARIABLE}): "
             "without one anybody on the network could run commands as you"
         )
+    if client_origins and not token:
+        raise SystemExit(
+            "zettcode gateway: --client-origin needs a token: without one another site could drive the gateway"
+        )
     return Settings(
         token=token,
         host=host,
@@ -190,6 +245,7 @@ def settings_from(argv: list[str] | None = None, *, base: Settings | None = None
         allow_full=allow_full,
         directory=directory,
         log_level=log_level,
+        client_origins=client_origins,
     )
 
 
@@ -351,6 +407,8 @@ def spawn(settings: Settings) -> subprocess.Popen[bytes]:
         arguments.append("--no-full")
     for root in settings.roots:
         arguments.extend(("--root", str(root)))
+    for source in settings.client_origins:
+        arguments.extend(("--client-origin", source))
     environment = {**os.environ, TOKEN_VARIABLE: settings.token}
     options: dict[str, Any] = {
         "stdin": subprocess.DEVNULL,

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/src/zettcode/gateway/runfile.py

@@ -66,6 +66,7 @@ def write(settings: Settings) -> None:
         "roots": [str(root) for root in settings.roots],
         "allow_full": settings.allow_full,
         "log_level": settings.log_level,
+        "client_origins": list(settings.client_origins),
     }
     descriptor, temporary = tempfile.mkstemp(dir=settings.directory, prefix=".run-", suffix=".tmp")
     try:
@@ -96,6 +97,7 @@ def read(directory: Path) -> Running | None:
     pid, port = raw.get("pid"), raw.get("port")
     host, token, log_level = raw.get("host"), raw.get("token"), raw.get("log_level")
     roots, allow_full = raw.get("roots"), raw.get("allow_full")
+    client_origins = raw.get("client_origins", [])
     if not (_whole(pid) and pid > 0 and _whole(port) and 0 < port < 65536):
         return None
     if not (isinstance(host, str) and isinstance(token, str) and isinstance(log_level, str)):
@@ -104,6 +106,8 @@ def read(directory: Path) -> Running | None:
         return None
     if not isinstance(roots, list) or not all(isinstance(root, str) for root in roots):
         return None
+    if not isinstance(client_origins, list) or not all(isinstance(item, str) for item in client_origins):
+        return None
     settings = Settings(
         token=token,
         host=host,
@@ -114,6 +118,7 @@ def read(directory: Path) -> Running | None:
         # folder.
         directory=directory,
         log_level=log_level,
+        client_origins=tuple(client_origins),
     )
     return Running(pid, settings)
 

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/src/zettcode/gateway/settings.py

@@ -13,6 +13,11 @@ DIRECTORY_VARIABLE = "ZETTCODE_GATEWAY_DIR"
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 8765
 
+#: The origin the desktop client runs under: Electron's ``app://`` page. A gateway with a token lets it in; with no
+#: token it is ignored, because then the origin check is the only thing between another site and a gateway that runs
+#: commands. The Android app loads the gateway's own page at the gateway's origin and needs no entry here.
+APP_ORIGINS = ("app://-",)
+
 
 def default_directory() -> Path:
     """Return the gateway's own folder: ``$ZETTCODE_GATEWAY_DIR``, or ``~/.zettcode/gateway``."""
@@ -35,6 +40,8 @@ class Settings:
             command line (``--no-full`` turns it off), never from the page.
         directory: The gateway's own folder: its workspace, the id of its session, and what the page remembers.
         log_level: uvicorn's log level.
+        client_origins: Extra origins a native client or a page of its own is served from, on top of
+            :data:`APP_ORIGINS`. Ignored without a token.
     """
 
     token: str = ""
@@ -44,12 +51,24 @@ class Settings:
     allow_full: bool = False
     directory: Path = field(default_factory=default_directory)
     log_level: str = "info"
+    client_origins: tuple[str, ...] = ()
 
     @property
     def open(self) -> bool:
         """Return whether anybody who can reach the gateway may use it, with no token."""
         return not self.token
 
+    @property
+    def allowed_origins(self) -> tuple[str, ...]:
+        """Return the origins besides the gateway's own that may call it, and may write to it.
+
+        Empty when there is no token. The token is what keeps people out; an origin is not a credential, so letting a
+        native client's origin through is only safe while every request still has to show the token.
+        """
+        if self.open:
+            return ()
+        return tuple(dict.fromkeys((*APP_ORIGINS, *self.client_origins)))
+
     @property
     def workspace(self) -> Path:
         """Return the directory the gateway's own session works in: it has nothing to edit, and its name is public."""

{zettcode_gateway-0.4.0 → zettcode_gateway-0.4.2}/src/zettcode/gateway/static/app.css

@@ -1376,6 +1376,64 @@ a.member:hover { background: var(--hover);
 }
 
 
+/* src/components/shell/ServerGate.vue */
+
+.gate { height: 100%; overflow-y: auto; background: var(--surface-2); overscroll-behavior: contain;
+}
+.gate-inner {
+  width: 100%; max-width: 34rem; margin: 0 auto; padding: calc(24px + var(--safe-top)) 16px calc(28px + var(--safe-bottom));
+  display: flex; flex-direction: column; gap: 12px;
+}
+.gate-head { display: flex; align-items: center; gap: 14px; padding: 8px 4px 4px;
+}
+.gate-head img { object-fit: contain; flex: none;
+}
+.gate-head h1 { margin: 0; font-size: 1.45rem; line-height: 1.15;
+}
+.gate-head p { margin: 4px 0 0; color: var(--muted); font-size: 0.92rem; line-height: 1.35;
+}
+.gate-form { margin: 0; padding-bottom: 4px;
+}
+.gate-field { display: flex; flex-direction: column; gap: 4px; padding: 9px 16px;
+}
+.gate-field + .gate-field { border-top: 1px solid var(--divider);
+}
+.gate-field span { color: var(--muted); font-size: 0.78rem; font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase;
+}
+.gate-field input { width: 100%; min-width: 0; border: 0; outline: 0; background: none; color: var(--text); font-size: 1rem; padding: 4px 0;
+}
+.gate-server { display: flex; align-items: center; gap: 2px; padding-right: 4px;
+}
+.gate-server + .gate-server { border-top: 1px solid var(--divider);
+}
+.gate-pick {
+  display: flex; align-items: center; gap: 12px; flex: 1; min-width: 0; min-height: 64px; padding: 8px 12px 8px 16px;
+  text-align: left; color: inherit; transition: background 0.12s;
+}
+.gate-pick:hover { background: var(--hover);
+}
+.gate-plug { display: grid; place-items: center; width: 38px; height: 38px; border-radius: 11px; background: var(--accent-soft); color: var(--accent); flex: none;
+}
+.gate-text { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 2px;
+}
+.gate-text b { font-weight: 600; font-size: 1rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.gate-text small { color: var(--muted); font-family: var(--mono); font-size: 0.76rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.gate-active { color: var(--ok); flex: none;
+}
+.gate-hint { margin: 0; padding: 4px 6px; color: var(--muted); font-size: 0.8rem; line-height: 1.4; text-align: center;
+}
+.gate .iconbtn.danger { color: var(--bad);
+}
+.gate .iconbtn.danger:hover { background: var(--bad-soft);
+}
+@media (max-width: 719px) {
+.gate-inner { padding-left: 10px; padding-right: 10px;
+}
+}
+
+
 /* src/components/shell/WelcomeMain.vue */
 
 .welcome { flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 10px; padding: 24px; text-align: center; color: var(--muted); background: var(--surface-2);