@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import secrets
+import sys
+from pathlib import Path
+
+from .auth import AuthConfig, is_loopback_host
+from .egress import read_egress_policy, set_egress_policy
+from .origins import parse_allowed_origins
+from .server import create_runtime_server
+
+
+def _read_integer(value: str | None, fallback: int) -> int:
+    if not value:
+        return fallback
+    try:
+        return int(value)
+    except ValueError:
+        return fallback
+
+
+def _resolve_mount_secret() -> str:
+    """The key public mount addresses are derived from.
+
+    Taken from the environment where there is one, so a deployment can hold it
+    with its other secrets and several instances behind a load balancer agree on
+    the addresses they serve. Otherwise drawn once and kept beside the rest of
+    this runtime's data, because the alternative — a fresh key per start — is
+    what makes an endpoint configured in somebody else's product stop working
+    after a restart.
+    """
+    from_env = os.environ.get("HKP_MOUNT_SECRET")
+    if from_env:
+        return from_env
+
+    file = Path.home() / ".hkp" / "python" / "mount-secret"
+    try:
+        existing = file.read_text().strip()
+        if existing:
+            return existing
+    except OSError:
+        # Not written yet, which is the first start on this machine.
+        pass
+
+    secret = secrets.token_hex(32)
+    try:
+        file.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+        file.write_text(f"{secret}\n")
+        file.chmod(0o600)
+    except OSError as err:
+        print(
+            "[hkp-python] Could not persist the mount secret, so public endpoint "
+            f"addresses will change on restart: {err}",
+            file=sys.stderr,
+        )
+    return secret
+
+
+def _load_env_file() -> None:
+    """Minimal .env loader (KEY=VALUE lines), matching hkp-node's dotenv
+    behaviour: real environment variables win. Looks next to the project root
+    first, then in the working directory, which is where the file sits when the
+    package is installed rather than run from a checkout."""
+    env_path = Path(__file__).resolve().parents[2] / ".env"
+    if not env_path.is_file():
+        env_path = Path.cwd() / ".env"
+    if not env_path.is_file():
+        return
+    for line in env_path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("'\"")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def _parse_allowed_emails(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    emails = [email.strip().lower() for email in value.split(",")]
+    emails = [email for email in emails if email]
+    return emails or None
+
+
+def _parse_audiences(value: str | None) -> list[str]:
+    """Accepted ``aud`` values, comma-separated. Several is the normal case: the
+    web and native apps are necessarily separate Auth0 applications, so the
+    id_tokens they issue carry different client ids while both address this one
+    runtime."""
+    if not value:
+        return []
+    audiences = [audience.strip() for audience in value.split(",")]
+    return [audience for audience in audiences if audience]
+
+
+def _is_dev_checkout() -> bool:
+    """A development checkout runs from the source tree; an installed package
+    runs from site-packages/dist-packages. Only the former may opt out of
+    authentication (mirrors hkp-node's node_modules check)."""
+    parts = Path(__file__).resolve().parts
+    return "site-packages" not in parts and "dist-packages" not in parts
+
+
+def resolve_server_auth_config(host: str) -> AuthConfig:
+    """Fail closed: refuse to start without authentication unless the server is
+    reachable only locally (loopback bind) or this is a source checkout that
+    explicitly opts in via ALLOW_NO_AUTH=true. An installed package bound to a
+    public interface can never reach no-auth mode."""
+    domain = os.environ.get("AUTH0_DOMAIN")
+    audience = _parse_audiences(os.environ.get("AUTH0_AUDIENCE"))
+    allowed_emails = _parse_allowed_emails(os.environ.get("ALLOWED_EMAILS"))
+    if domain and audience:
+        if allowed_emails:
+            print(
+                f"[hkp-python] Access restricted to {len(allowed_emails)} allowlisted email(s)."
+            )
+        return AuthConfig(
+            mode="jwt",
+            domain=domain,
+            audience=audience,
+            allowed_emails=allowed_emails,
+        )
+
+    # An allowlist without JWT auth cannot be enforced; starting anyway would
+    # silently grant access to everyone the operator meant to exclude.
+    if allowed_emails:
+        print(
+            "[hkp-python] ALLOWED_EMAILS is set but AUTH0_DOMAIN/AUTH0_AUDIENCE are not. "
+            "The email allowlist can only be enforced with Auth0 configured — refusing to start.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if is_loopback_host(host):
+        print(
+            f"[hkp-python] No Auth0 configured; bound to loopback ({host}), so the server "
+            "is reachable only from this machine. Running without authentication.",
+            file=sys.stderr,
+        )
+        return AuthConfig(mode="none")
+
+    if _is_dev_checkout() and os.environ.get("ALLOW_NO_AUTH") == "true":
+        print(
+            "[hkp-python] AUTH0_DOMAIN/AUTH0_AUDIENCE not set and ALLOW_NO_AUTH=true — running "
+            f"with NO AUTHENTICATION on a non-loopback bind ({host}). Local development only; never expose this.",
+            file=sys.stderr,
+        )
+        return AuthConfig(mode="none")
+
+    print(
+        f"[hkp-python] Refusing to start without authentication on a non-loopback bind ({host}). "
+        "Set AUTH0_DOMAIN and AUTH0_AUDIENCE, bind to 127.0.0.1 for local-only use, or "
+        "(from a checkout) set ALLOW_NO_AUTH=true.",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+async def main() -> None:
+    if not os.environ.get("SKIP_LOADING_ENV"):
+        _load_env_file()
+
+    port = _read_integer(os.environ.get("PORT"), 8080)
+    host = os.environ.get("HOST", "0.0.0.0")
+    external_host = os.environ.get("EXTERNAL_HOST", "127.0.0.1")
+    allowed_origins = parse_allowed_origins(os.environ.get("ALLOWED_ORIGINS"))
+    # Before anything can dial out: a hosted server reaches only public
+    # addresses on a board's behalf (egress.py).
+    egress = read_egress_policy(os.environ)
+    set_egress_policy(egress)
+    if egress.mode == "public":
+        print(
+            "[hkp-python] HKP_EGRESS=public: boards reach public addresses only"
+            + (f", and {len(egress.allow)} allowed address(es) or range(s)" if egress.allow else ""),
+            file=sys.stderr,
+        )
+    auth_config = resolve_server_auth_config(host)
+
+    server = create_runtime_server(
+        {
+            "allowed_origins": allowed_origins,
+            "auth": auth_config,
+            "external_host": external_host,
+            "host": host,
+            "mount_secret": _resolve_mount_secret(),
+            # The tickets this server reconnects to coordinators with, beside
+            # the mount secret. HKP_COORDINATOR_LINKS_FILE="" keeps them in
+            # memory, so a restart leaves every deployed board waiting to be
+            # deployed again.
+            "coordinator_links": os.environ.get(
+                "HKP_COORDINATOR_LINKS_FILE",
+                str(Path.home() / ".hkp" / "python" / "coordinator-links.json"),
+            ),
+            "quotas": {
+                "max_runtimes_per_user": _read_integer(
+                    os.environ.get("HKP_MAX_RUNTIMES_PER_USER"), 0
+                ),
+                "max_services_per_runtime": _read_integer(
+                    os.environ.get("HKP_MAX_SERVICES_PER_RUNTIME"), 0
+                ),
+                "min_timer_interval_ms": _read_integer(
+                    os.environ.get("HKP_MIN_TIMER_INTERVAL_MS"), 0
+                ),
+                **(
+                    {
+                        "max_request_body_bytes": _read_integer(
+                            os.environ["HKP_MAX_REQUEST_BODY_BYTES"], 0
+                        )
+                    }
+                    if os.environ.get("HKP_MAX_REQUEST_BODY_BYTES")
+                    else {}
+                ),
+            },
+        }
+    )
+
+    address = await server.start(port, host)
+    # Once this server is listening: a coordinator it reconnects to may build a
+    # runtime at once, and that runtime's mounts need an address to publish.
+    server.coordinator_links.restore()
+    print(f"hkp-python listening on {address['base_url']}")
+
+    try:
+        await asyncio.Event().wait()
+    except (KeyboardInterrupt, SystemExit):
+        pass
+    finally:
+        await server.stop()
+
+
+def run() -> None:
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

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

@@ -0,0 +1,56 @@
+"""Addressing a service inside a scope.
+
+A runtime's services are a flat list, and a uuid names one of them. A service
+holding a pipeline of its own — a SubService, an endpoint, Tracks — has
+services inside it that the flat list does not reach, and until now nothing
+outside could name one. A **scoped address** names it by the path through the
+services containing it::
+
+    read.kept-articles          the `kept-articles` inside the `read` scope
+    read.list.feed-doc          two levels down
+
+**The separator is a dot, and that is forced rather than chosen.** A service
+address is carried in a URL path segment (``/runtimes/{id}/services/{id}``),
+which a slash would split; the same constraint already picked a dot for the
+separator between a unit's name and its runtime ids.
+
+**A flat uuid is tried before the path is walked**, so a board whose service
+uuid happens to contain a dot keeps resolving to that service rather than being
+read as an address into something else.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+ADDRESS_SEPARATOR = "."
+
+
+def split_address(address: str) -> list[str]:
+    """``["read", "kept-articles"]`` for ``"read.kept-articles"``."""
+    return [part for part in address.split(ADDRESS_SEPARATOR) if part]
+
+
+def join_address(owner: str, instance_id: str) -> str:
+    """The address of ``instance_id`` inside ``owner``."""
+    return f"{owner}{ADDRESS_SEPARATOR}{instance_id}" if owner else instance_id
+
+
+def is_scoped_address(address: str) -> bool:
+    """True where an address names something nested rather than a flat uuid."""
+    return len(split_address(address)) > 1
+
+
+def descend(service: Any, segments: list[str]) -> Any | None:
+    """Walk the rest of an address down from a service already resolved.
+
+    Answers None at the first segment nothing claims, rather than the nearest
+    service it did reach: a partial address is a miss, not a match.
+    """
+    current = service
+    for segment in segments:
+        find_nested = getattr(current, "find_nested", None)
+        current = find_nested(segment) if find_nested else None
+        if current is None:
+            return None
+    return current