gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/host_surfaces.py

@@ -0,0 +1,275 @@
+"""The UI and browser surfaces of a World Host session.
+
+The api surface is the world's own routes, answered by :class:`WorldApp`. The
+two surfaces here are what a *person* (or an agent driving a browser) reaches:
+
+* **ui** — ``w-<sid>.<domain>``: the version's prebuilt static UI (``[ui]
+  static = "ui/static"`` in ``gateway-api-world.toml``), a single-page app served
+  straight from the version cache with an SPA fallback, plus its same-origin
+  ``api_path`` prefix rewritten onto the session's own api. The pod engine
+  builds this into an nginx image per version; the host serves the files.
+* **browser** — ``w-<sid>-cdp.<domain>``: a websocket tunnel to the Chromium
+  the platform leased for the session from the browser pool (one
+  ``deploy/world-browser`` relay per session, single use). The host checks the
+  per-session token or live grant, then pipes bytes.
+
+A browser cannot set an ``Authorization`` header on a page load, so the ui
+surface admits a session token from a cookie as well: the first request
+carries ``?token=`` (the URL the platform hands out), the host answers with the
+cookie and a redirect to the same URL without it, and every request after
+that — pages, assets, ``api_path`` calls — is admitted by the cookie.
+"""
+
+from __future__ import annotations
+
+import hmac
+import mimetypes
+import selectors
+import socket
+import time
+import urllib.parse
+from dataclasses import dataclass
+from http.cookies import SimpleCookie
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from .validation import fail
+
+API_BUNDLE = "gateway-api-world.toml"
+#: The cookie the ui surface admits a session by.
+SESSION_COOKIE = "__world_session"
+#: Query parameter that carries the session token exactly once, on the way in.
+TOKEN_QUERY = "token"
+#: Marks a request another host already forwarded once; never sent on again.
+HOP_HEADER = "x-worlds-hop"
+#: Headers copied from a websocket client's upgrade request upstream.
+UPGRADE_HEADERS = (
+    HOP_HEADER,
+    "upgrade",
+    "connection",
+    "sec-websocket-key",
+    "sec-websocket-version",
+    "sec-websocket-protocol",
+    "sec-websocket-extensions",
+    "origin",
+    "user-agent",
+)
+#: Live-view grant scopes, as ``deploy/world-browser/relay.mjs`` knows them.
+LIVE_SCOPES = ("view", "control")
+TUNNEL_CONNECT_TIMEOUT_S = 10.0
+TUNNEL_BUFFER = 64 * 1024
+
+
+# --------------------------------------------------------------------------- #
+# The static ui.
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class UiSurface:
+    #: The directory holding ``index.html`` and the built assets.
+    root: Path
+    #: The page an agent lands on first.
+    entry: str
+    #: Same-origin prefix the SPA calls the api at, or None when it has none.
+    api_path: str | None
+
+
+def load_ui_surface(bundle: Path) -> UiSurface | None:
+    """The bundle's static ui, or None when its manifest declares none.
+    ``[ui] static`` names a directory inside the bundle; one that is missing,
+    outside the bundle or without an ``index.html`` is refused at open, so a
+    session never advertises a ui that would 404."""
+    manifest = bundle / API_BUNDLE
+    if not manifest.is_file():
+        return None
+    data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    ui = data.get("ui")
+    if not isinstance(ui, dict):
+        return None
+    static = ui.get("static")
+    if not isinstance(static, str) or not static:
+        return None
+    bundle_root = bundle.resolve()
+    root = (bundle_root / static).resolve()
+    if root != bundle_root and bundle_root not in root.parents:
+        fail("host", f"[ui].static = {static!r} points outside the bundle")
+    if not (root / "index.html").is_file():
+        fail("host", f"[ui].static = {static!r} has no index.html; build the ui before pushing")
+    entry = ui.get("entry")
+    api_path = ui.get("api_path")
+    return UiSurface(
+        root=root,
+        entry=entry if isinstance(entry, str) and entry.startswith("/") else "/",
+        api_path=(
+            api_path.rstrip("/") if isinstance(api_path, str) and api_path.startswith("/") and api_path != "/" else None
+        ),
+    )
+
+
+def api_target(ui: UiSurface, path: str) -> str | None:
+    """The api route a ui-origin ``path`` proxies to, or None when the path is
+    a page or an asset. ``/__world-api/v1/charges`` → ``/v1/charges``."""
+    prefix = ui.api_path
+    if prefix is None:
+        return None
+    if path == prefix:
+        return "/"
+    if path.startswith(prefix + "/"):
+        return path[len(prefix) :]
+    return None
+
+
+def static_file(ui: UiSurface, path: str) -> tuple[int, dict[str, str], bytes]:
+    """One static response: the file at ``path`` under the ui root, or
+    ``index.html`` for a client-side route (a path with no extension). A path
+    that escapes the root, or names a missing asset, is a 404."""
+    rel = urllib.parse.unquote(path).lstrip("/")
+    candidate = (ui.root / rel).resolve() if rel else ui.root / "index.html"
+    if candidate != ui.root and ui.root not in candidate.parents:
+        return 404, {"content-type": "application/json"}, b'{"error":"not found"}'
+    if candidate.is_dir():
+        candidate = candidate / "index.html"
+    if not candidate.is_file():
+        if Path(rel).suffix:
+            return 404, {"content-type": "application/json"}, b'{"error":"not found"}'
+        candidate = ui.root / "index.html"
+    kind, _ = mimetypes.guess_type(candidate.name)
+    content_type = kind or "application/octet-stream"
+    if content_type.startswith("text/") or content_type in ("application/javascript", "application/json"):
+        content_type += "; charset=utf-8"
+    # Hashed assets live forever; index.html and anything unhashed must be
+    # re-checked so a new version's UI is what the agent sees.
+    cache = "public, max-age=31536000, immutable" if "assets/" in rel else "no-cache"
+    return 200, {"content-type": content_type, "cache-control": cache}, candidate.read_bytes()
+
+
+# --------------------------------------------------------------------------- #
+# Admitting a person: the token cookie.
+# --------------------------------------------------------------------------- #
+
+
+def cookie_token(headers: dict[str, str]) -> str | None:
+    """The session token a request's cookie carries, if any."""
+    raw = headers.get("cookie")
+    if not raw:
+        return None
+    jar: SimpleCookie = SimpleCookie()
+    try:
+        jar.load(raw)
+    except Exception:  # noqa: BLE001 - a malformed cookie header admits nothing
+        return None
+    morsel = jar.get(SESSION_COOKIE)
+    return morsel.value if morsel is not None else None
+
+
+def query_token(query: str) -> str | None:
+    values = urllib.parse.parse_qs(query, keep_blank_values=False).get(TOKEN_QUERY)
+    return values[0] if values else None
+
+
+def without_query_token(url: urllib.parse.SplitResult) -> str:
+    """The same request URL with ``?token=`` removed, for the redirect that
+    follows the cookie exchange."""
+    pairs = [(k, v) for k, v in urllib.parse.parse_qsl(url.query, keep_blank_values=True) if k != TOKEN_QUERY]
+    return urllib.parse.urlunsplit(("", "", url.path or "/", urllib.parse.urlencode(pairs), ""))
+
+
+def session_cookie(token: str, *, secure: bool, max_age_s: float) -> str:
+    """The ``Set-Cookie`` value that admits this session. ``HttpOnly`` keeps it
+    from the SPA's own scripts; ``SameSite=Lax`` keeps other origins from
+    riding it; ``Secure`` is set unless the deployment says its public surface
+    is plain http (a dev host, ``WORLDS_HOST_PLAIN_HTTP=1``); ``Max-Age``
+    is the session's lease, so the browser forgets the credential when the
+    host would have, instead of keeping it for the profile's lifetime."""
+    attrs = [f"{SESSION_COOKIE}={token}", "Path=/", f"Max-Age={int(max_age_s)}", "HttpOnly", "SameSite=Lax"]
+    if secure:
+        attrs.append("Secure")
+    return "; ".join(attrs)
+
+
+def matches(candidate: str | None, token: str) -> bool:
+    return candidate is not None and hmac.compare_digest(candidate, token)
+
+
+# --------------------------------------------------------------------------- #
+# Live-view grants: the relay's scheme, so a console viewer needs no token.
+# --------------------------------------------------------------------------- #
+
+
+def mint_live_grant(token: str, ttl_ms: int, scope: str = "view", now_ms: int | None = None) -> str:
+    """``<expiresAtMs>.<scope>.<hmac>`` signed with ``token`` — the format
+    ``deploy/world-browser/relay.mjs`` verifies."""
+    if scope not in LIVE_SCOPES:
+        raise ValueError(f"unknown live scope {scope}")
+    exp = str((int(time.time() * 1000) if now_ms is None else now_ms) + ttl_ms)
+    sig = hmac.new(token.encode(), f"live:{scope}:{exp}".encode(), "sha256").hexdigest()
+    return f"{exp}.{scope}.{sig}"
+
+
+def verify_live_grant(grant: str, token: str, now_ms: int | None = None) -> str | None:
+    """The grant's scope when it verifies against ``token`` and has not
+    expired, else None."""
+    parts = grant.split(".")
+    if len(parts) != 3 or not token:
+        return None
+    exp, scope, sig = parts
+    if not exp.isdigit() or len(exp) > 16 or scope not in LIVE_SCOPES or len(sig) != 64:
+        return None
+    if int(exp) <= (int(time.time() * 1000) if now_ms is None else now_ms):
+        return None
+    expected = hmac.new(token.encode(), f"live:{scope}:{exp}".encode(), "sha256").hexdigest()
+    return scope if hmac.compare_digest(sig, expected) else None
+
+
+# --------------------------------------------------------------------------- #
+# The websocket tunnel.
+# --------------------------------------------------------------------------- #
+
+
+def tunnel(client: socket.socket, target: str, path: str, headers: dict[str, str], host: str | None = None) -> None:
+    """Pipe a websocket client through to ``target`` (``ws://host:port``): send
+    the upgrade request for ``path`` with the client's handshake headers, then
+    copy bytes both ways until either side closes. The client's request line
+    and headers have already been read by the caller; a websocket client sends
+    nothing more until it has the ``101``, so nothing of its is lost. ``host``
+    is the ``Host`` presented upstream: the session's origin when the hop is
+    to another world host (which routes by it), the target's own by default."""
+    url = urllib.parse.urlsplit(target)
+    if url.scheme != "ws" or not url.hostname:
+        raise ValueError(f"browser url must be ws://host:port, not {target!r}")
+    upstream = socket.create_connection((url.hostname, url.port or 80), timeout=TUNNEL_CONNECT_TIMEOUT_S)
+    try:
+        lines = [f"GET {path} HTTP/1.1", f"Host: {host or url.netloc}"]
+        lines += [f"{name}: {headers[name]}" for name in UPGRADE_HEADERS if name in headers]
+        upstream.sendall(("\r\n".join(lines) + "\r\n\r\n").encode("latin-1"))
+        upstream.settimeout(None)
+        client.settimeout(None)
+        pump(client, upstream)
+    finally:
+        upstream.close()
+
+
+def pump(a: socket.socket, b: socket.socket) -> None:
+    """Copy bytes between two sockets until one of them closes."""
+    peers = {a.fileno(): (a, b), b.fileno(): (b, a)}
+    with selectors.DefaultSelector() as sel:
+        sel.register(a, selectors.EVENT_READ)
+        sel.register(b, selectors.EVENT_READ)
+        while True:
+            for key, _ in sel.select():
+                source, sink = peers[key.fd]
+                try:
+                    data = source.recv(TUNNEL_BUFFER)
+                except OSError:
+                    return
+                if not data:
+                    return
+                try:
+                    sink.sendall(data)
+                except OSError:
+                    return