@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-python/src/hkp/mounts.py

@@ -0,0 +1,288 @@
+"""Public service endpoints, served by the shared runtime server.
+
+Mirrors hkp-node's ``src/mounts.ts``.
+"""
+from __future__ import annotations
+
+import hmac
+import secrets
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any, Awaitable, Callable, Protocol
+
+from aiohttp import web
+
+#: Requests under this prefix are served by mounts rather than the REST API.
+MOUNT_PREFIX = "/hosted"
+
+
+@dataclass
+class MountContext:
+    """Where a mount is served and how much of the request path belongs to it."""
+
+    #: Public path prefix this mount owns, e.g. ``/hosted/ab12…``.
+    mount_path: str
+    #: Request target with ``mount_path`` removed; always starts with ``/`` and
+    #: keeps any query string, so a handler can parse it as a URL and see both.
+    sub_path: str
+
+
+MountHandler = Callable[[web.Request, MountContext], Awaitable[web.StreamResponse]]
+
+
+@dataclass
+class MountHandle:
+    """A live mount, handed back to the service that registered it."""
+
+    #: Public URL clients should be pointed at.
+    url: str
+    #: Path prefix of ``url``, for clients configured by host/port/path.
+    path: str
+    release: Callable[[], None]
+
+
+@dataclass
+class _MountRecord:
+    owner: str
+    space: str
+    runtime_id: str
+    service_uuid: str
+    handler: MountHandler
+
+
+class MountRegistry:
+    """Routes public traffic to services that need to expose an endpoint,
+    without any of them binding a port of their own.
+
+    A service asks for a mount and gets back an opaque, server-assigned id. That
+    id — rather than a port or a caller-chosen path — is what makes the endpoint
+    addressable, which matters for three reasons:
+
+    - Ports are a single machine-wide namespace. With several tenants on one
+      host, a service asking for a specific port is a land grab: the second
+      claimant fails, and whoever wins receives traffic the other expected.
+    - Runtime ids are only unique per tenant (boards ship stable ones like
+      ``node``), so they cannot appear in a globally-routable path.
+    - These endpoints are deliberately unauthenticated — they exist to be called
+      by outside parties. An unguessable id therefore doubles as the capability
+      to reach them, and it carries no user identifier that a public URL would
+      otherwise leak.
+
+    The id is **derived, not drawn**: an HMAC of who owns the mount, which board
+    and runtime it is in, and what it is called, keyed by a secret only the
+    server holds. Randomness would be just as unguessable and was what this did
+    first, but it made the address change every time a board was loaded — so
+    anything outside pointing at it (a webhook configured in somebody else's
+    product) broke on every restart, and a board could not be redeployed without
+    reconfiguring its callers.
+
+    Deriving it keeps the address stable across reloads, restarts and redeploys
+    while keeping the secret out of the board: the board says only what the mount
+    is *called*, which is not sensitive, and the server turns that into an
+    address nobody can compute without the key. Rotating the key rotates every
+    endpoint, and renaming one mount rotates only that one.
+    """
+
+    def __init__(
+        self,
+        public_url_for: Callable[[str], str | None],
+        secret: str | None = None,
+    ) -> None:
+        #: Resolves a mount path to the URL clients should use. Returns None
+        #: before the server is listening, since the port is not known until then.
+        self._public_url_for = public_url_for
+        #: Keys the id derivation. A server that is given none draws one for this
+        #: process, which is the old behaviour: addresses that work but do not
+        #: survive a restart. ``__main__`` persists one so they do.
+        self._secret = secret or secrets.token_hex(32)
+        #: Every claim to an address, oldest first. An address is derived
+        #: from what the mount is called, so more than one runtime may claim
+        #: the same one: a runtime rebuilt under its id claims it before the
+        #: one it replaces lets go, and a board open in a client and also
+        #: deployed holds two copies of each of its mounts. One claim answers
+        #: — see ``_answering`` — and the others are kept, so that releasing
+        #: one leaves the address with whoever still claims it.
+        self._mounts: dict[str, list[_MountRecord]] = {}
+
+    def _derive_id(
+        self,
+        owner: str,
+        board_name: str,
+        runtime_id: str,
+        name: str,
+    ) -> str:
+        """The address a given mount always gets.
+
+        Every part that identifies the mount goes in, so two services cannot
+        derive the same id: the tenant, the board, the runtime, and the mount's
+        name. NUL separates them, as it cannot occur in any of them — the same
+        reasoning as ``_tenant_key`` in the server.
+        """
+        message = "\u0000".join([owner, board_name, runtime_id, name])
+        digest = hmac.new(
+            self._secret.encode("utf-8"), message.encode("utf-8"), sha256
+        ).hexdigest()
+        return digest[:32]
+
+    def register(
+        self,
+        owner: str,
+        runtime_id: str,
+        service_uuid: str,
+        handler: MountHandler,
+        # What the mount is called, and the board's, so the address survives a
+        # reload. A service that names nothing is identified by its own uuid,
+        # which is stable in a board file too.
+        board_name: str = "",
+        mount_name: str | None = None,
+        # The space the runtime lives in; see ``runtime.board_space``.
+        space: str | None = None,
+    ) -> MountHandle | None:
+        mount_id = self._derive_id(
+            owner, board_name, runtime_id, mount_name or service_uuid
+        )
+        mount_path = f"{MOUNT_PREFIX}/{mount_id}"
+        url = self._public_url_for(mount_path)
+        if not url:
+            return None
+
+        record = _MountRecord(
+            owner=owner,
+            space=owner if space is None else space,
+            runtime_id=runtime_id,
+            service_uuid=service_uuid,
+            handler=handler,
+        )
+        self._mounts.setdefault(mount_id, []).append(record)
+
+        def release() -> None:
+            # This claim and no other.
+            self._drop(mount_id, lambda claim: claim is record)
+
+        return MountHandle(url=url, path=mount_path, release=release)
+
+    def _answering(self, mount_id: str) -> _MountRecord | None:
+        """The claim that answers at an address: a deployed board's before a
+        client's, and the newest of its kind.
+
+        A board somebody deployed is meant to be reachable whoever else has it
+        open, so opening it in a client neither takes its address nor, on
+        leaving, takes the address away.
+        """
+        claims = self._mounts.get(mount_id, [])
+        deployed = [claim for claim in claims if claim.space != claim.owner]
+        if deployed:
+            return deployed[-1]
+        return claims[-1] if claims else None
+
+    def _drop(self, mount_id: str, gone: Callable[[_MountRecord], bool]) -> None:
+        claims = self._mounts.get(mount_id)
+        if claims is None:
+            return
+        kept = [claim for claim in claims if not gone(claim)]
+        if kept:
+            self._mounts[mount_id] = kept
+        else:
+            del self._mounts[mount_id]
+
+    def release_runtime(self, space: str, runtime_id: str) -> None:
+        """Drop every mount belonging to a runtime.
+
+        Services release their own mounts on destroy; this is the backstop so a
+        torn-down runtime can never leave a publicly reachable endpoint behind.
+        """
+        for mount_id in list(self._mounts):
+            self._drop(
+                mount_id,
+                lambda claim: claim.space == space and claim.runtime_id == runtime_id,
+            )
+
+    def release_owner(self, owner: str) -> None:
+        """Drops the mounts of what a tenant's clients created; a deployed
+        board's go with its runtimes."""
+        for mount_id in list(self._mounts):
+            self._drop(mount_id, lambda claim: claim.space == owner)
+
+    def count_for_owner(self, owner: str) -> int:
+        return sum(
+            1
+            for claims in self._mounts.values()
+            for claim in claims
+            if claim.owner == owner
+        )
+
+    async def handle(self, request: web.Request) -> web.StreamResponse:
+        """Serve a request addressed to a mount, or 404 when the id is unknown."""
+        mount_id = request.match_info.get("mount_id", "")
+        record = self._answering(mount_id)
+        if not record:
+            raise web.HTTPNotFound()
+
+        sub_path = request.match_info.get("sub_path", "")
+        if not sub_path.startswith("/"):
+            sub_path = "/" + sub_path
+        if request.query_string:
+            sub_path = f"{sub_path}?{request.query_string}"
+
+        context = MountContext(
+            mount_path=f"{MOUNT_PREFIX}/{mount_id}",
+            sub_path=sub_path,
+        )
+        return await record.handler(request, context)
+
+
+class MountFactory(Protocol):
+    def __call__(
+        self,
+        service_uuid: str,
+        handler: MountHandler,
+        board_name: str = "",
+        mount_name: str | None = None,
+    ) -> MountHandle | None: ...
+
+
+@dataclass
+class RuntimeMounts:
+    """Grants a runtime's services public endpoints. Supplied by the server,
+    which owns the listening socket; absent for inner sub-service pipelines,
+    which are not addressable from outside."""
+
+    mount: MountFactory
+
+
+def decode_body(body: bytes, content_type: str | None) -> Any:
+    """Decode a body for the content types where a board would otherwise be
+    stuck with raw bytes.
+
+    Returns ``None`` when there is nothing sensible to produce, which includes
+    malformed input: a public endpoint receives whatever it is given, and a
+    parse failure should leave the raw bytes to inspect rather than fail the
+    request.
+    """
+    import json
+    from urllib.parse import parse_qsl
+
+    if not body:
+        return None
+
+    media = (content_type or "").split(";")[0].strip().lower()
+
+    if media == "application/json" or media.endswith("+json"):
+        try:
+            return json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return None
+
+    if media == "application/x-www-form-urlencoded":
+        try:
+            return dict(parse_qsl(body.decode("utf-8")))
+        except UnicodeDecodeError:
+            return None
+
+    if media.startswith("text/"):
+        try:
+            return body.decode("utf-8")
+        except UnicodeDecodeError:
+            return None
+
+    return None

package/bundle/hkp-python/src/hkp/origins.py

@@ -0,0 +1,169 @@
+"""Which browser pages may call this server, and when a request that carries
+no credential is let in.
+
+Being reachable only from this machine is not the same as being called only by
+this machine's owner: a page in their browser is a local caller too, and any
+site can address ``127.0.0.1``. So a request admitted without a credential — a
+server running without auth — must also not come from a foreign page, and must
+address the server by a name the server knows. A browser states the first in
+``Origin`` (or, on a request it sends without one, in ``Sec-Fetch-Site``) and
+the second in ``Host``; a page cannot forge either.
+
+A caller that is not a browser sends none of these, and is let in as before:
+another process on this machine is not what this guards against.
+
+A request a proxy passed on is never let in this way. A reverse proxy on the
+same host — nginx, Caddy — makes every request arrive from this machine at a
+name the server knows, so where it comes from says nothing any more. One that
+says so (``Forwarded``, ``X-Forwarded-For``, ``X-Real-IP``) is refused; one that
+says nothing cannot be told apart, which is why a loopback bind is a boundary
+only while nothing forwards to it.
+
+The same rule, row for row, is in hkp-node (``src/origins.ts``) and hkp-rt
+(``lib/include/origins.h``).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Mapping, Sequence, Union
+
+# The origins a server was told may call it, the way ``ALLOWED_ORIGINS`` gives
+# them:
+#
+# - ``"default"`` — nothing was said: the origins Readymade's own apps run
+#   from, and any page served from this machine;
+# - a list — exactly those;
+# - ``"*"`` — any origin, for a request that carries a credential. A request
+#   that carries none is never let in on the strength of ``*``: for it, ``*``
+#   reads as nothing was said.
+AllowedOrigins = Union[str, list[str]]
+
+DEFAULT_ORIGINS = "default"
+
+# Where the Readymade apps load their pages from: desktop, iOS, Android.
+_APP_ORIGINS = (
+    "saucer://embedded",
+    "hkp://app",
+    "https://appassets.androidplatform.net",
+)
+
+_HOST_PORT = re.compile(r"^(\[[^\]]*\]|[^:]+)(?::(\d+))?$")
+_IPV6_LITERAL = re.compile(r"^\[[0-9a-f:.]*:[0-9a-f:.]*\]$")
+_HTTP_ORIGIN = re.compile(r"^https?://(.*)$")
+
+
+def parse_allowed_origins(value: str | None) -> AllowedOrigins:
+    """Reads ``ALLOWED_ORIGINS``."""
+    trimmed = (value or "").strip()
+    if not trimmed:
+        return DEFAULT_ORIGINS
+    if trimmed == "*":
+        return "*"
+    origins = [origin.strip().lower() for origin in trimmed.split(",")]
+    return [origin for origin in origins if origin]
+
+
+def _is_ipv4_literal(host: str) -> bool:
+    """Four dot-separated numbers and nothing else. Strict, because the names
+    this is asked about come from a request: ``127.0.0.1.example.com`` is a
+    name somebody else resolves, not an address."""
+    parts = host.split(".")
+    return len(parts) == 4 and all(
+        part.isascii() and part.isdigit() and len(part) <= 3 and int(part) <= 255
+        for part in parts
+    )
+
+
+def _split_host(value: str) -> str | None:
+    """The host of ``host[:port]`` — a ``Host`` header, or what follows an
+    origin's scheme. None when it is neither."""
+    match = _HOST_PORT.match(value)
+    return match.group(1).lower() if match else None
+
+
+def _is_loopback_name(host: str) -> bool:
+    return (
+        host == "localhost"
+        or host == "[::1]"
+        or (_is_ipv4_literal(host) and host.startswith("127."))
+    )
+
+
+def is_loopback_origin(origin: str) -> bool:
+    """True for the origin of a page served from this machine, on any port."""
+    match = _HTTP_ORIGIN.match(origin.lower())
+    if not match:
+        return False
+    host = _split_host(match.group(1))
+    return host is not None and _is_loopback_name(host)
+
+
+def is_known_host(host_header: str | None, own_names: Sequence[str]) -> bool:
+    """True when a ``Host`` header names the server by something a page cannot
+    have arranged: an address, ``localhost``, or a name the server was told is
+    its own.
+
+    A page that resolves its own name to this machine (DNS rebinding) is
+    same-origin with the server as far as the browser can tell, and sends no
+    ``Origin`` to refuse — but the name it used is still in ``Host``. A request
+    without the header was not sent by a browser.
+    """
+    value = (host_header or "").strip()
+    if not value:
+        return True
+    host = _split_host(value)
+    if host is None:
+        return False
+    if host == "localhost" or _is_ipv4_literal(host) or _IPV6_LITERAL.match(host):
+        return True
+    return any(name and name.lower() == host for name in own_names)
+
+
+def allows_origin_without_credential(
+    origin: str | None, allowed: AllowedOrigins
+) -> bool:
+    """Whether a page at ``origin`` may call the server with nothing but where
+    it is calling from."""
+    value = (origin or "").strip().lower()
+    if not value:
+        return False
+    if isinstance(allowed, list):
+        return value in allowed
+    return value in _APP_ORIGINS or is_loopback_origin(value)
+
+
+def allows_origin(origin: str | None, allowed: AllowedOrigins) -> bool:
+    """Whether a page at ``origin`` may read what the server answers, and call
+    it with a credential."""
+    return allowed == "*" or allows_origin_without_credential(origin, allowed)
+
+
+_FORWARDING_HEADERS = ("Forwarded", "X-Forwarded-For", "X-Real-IP")
+
+
+def is_forwarded(headers: Mapping[str, str]) -> bool:
+    """Whether a request carries a header a proxy adds when it passes one on."""
+    return any((headers.get(name) or "").strip() for name in _FORWARDING_HEADERS)
+
+
+def admits_without_credential(
+    origin: str | None,
+    sec_fetch_site: str | None,
+    host: str | None,
+    allowed: AllowedOrigins,
+    own_names: Sequence[str],
+    forwarded: bool = False,
+) -> bool:
+    """Whether a request that carries no credential may be let in on the
+    strength of where it comes from. See the top of this file."""
+    if forwarded:
+        return False
+    if (origin or "").strip():
+        if not allows_origin_without_credential(origin, allowed):
+            return False
+    elif (sec_fetch_site or "").strip().lower() == "cross-site":
+        # A browser leaves ``Origin`` off a plain GET it makes for another
+        # site's page — an image, a script — and says so here instead.
+        return False
+    return is_known_host(host, own_names)