simulo 0.26.0__py3-none-any.whl

simulo/_client/login.py

@@ -0,0 +1,319 @@
+"""``simulo login`` — OAuth 2.0 Authorization Code + PKCE via browser loopback.
+
+Stdlib port of the ``simulo-backend`` parked CLI's ``simulo.cli.commands.auth``
+(``secrets``/``hashlib``/``http.server``/``webbrowser``/``urllib`` — no
+``click``, no ``httpx``). Mirrors the project's CLI-auth specification: PKCE generation, the loopback bind + capture flow,
+the manual out-of-band fallback for headless/remote-SSH environments, and the
+``/auth/cli/callback`` -> credentials-file field mapping.
+
+The one addition versus the backend CLI: the saved credentials also record
+``api_base_url`` (the base URL this login was performed against), so
+subsequent commands resolve the right platform without re-stating
+``SIMULO_ENV``/``SIMULO_API_URL`` every time (see ``config.resolve_base_url``).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import secrets
+import socket
+import time
+import urllib.parse
+import webbrowser
+from typing import Any, Optional
+from uuid import UUID
+
+from simulo._client import config
+from simulo._client import http as http_client
+from simulo._client.credentials import save_credentials
+
+CANDIDATE_PORTS = (8421, 8422, 8423)
+LOOPBACK_PATH = "/cli-callback"
+LOGIN_TIMEOUT_SECONDS = 300
+
+#: Same endpoint the backend CLI's SimuloClient calls — unauthenticated (the
+#: login endpoint itself; see cli-auth SKILL Control-Plane Endpoints table).
+CLI_CALLBACK_PATH = "/auth/cli/callback"
+
+
+class LoginError(RuntimeError):
+    """``simulo login`` could not complete (bad state, rejected code, no client id)."""
+
+
+def _require_canonical_organization_id(value: Any) -> str:
+    """Validate the UUID-backed organization binding before persisting it."""
+    if not isinstance(value, str):
+        raise LoginError("Login failed: malformed organization identity from the control plane.")
+    try:
+        canonical = str(UUID(value))
+    except ValueError as exc:
+        raise LoginError("Login failed: malformed organization identity from the control plane.") from exc
+    if canonical != value:
+        raise LoginError("Login failed: malformed organization identity from the control plane.")
+    return canonical
+
+
+# ---------------------------------------------------------------------------
+# PKCE helpers
+# ---------------------------------------------------------------------------
+
+
+def generate_pkce() -> tuple[str, str]:
+    """Return ``(code_verifier, code_challenge)``.
+
+    Verifier: 64 random bytes -> base64url-encoded (>=86 chars, URL-safe).
+    Challenge: SHA-256(verifier) -> base64url-encoded.
+    """
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(64)).rstrip(b"=").decode()
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+# ---------------------------------------------------------------------------
+# Loopback port binding + code capture
+# ---------------------------------------------------------------------------
+
+
+def bind_loopback() -> Optional[socket.socket]:
+    """Try to bind ``127.0.0.1`` on each candidate port in order.
+
+    Returns the bound socket on the first success, or ``None`` if all fail.
+    Binds to ``127.0.0.1`` ONLY — never ``0.0.0.0``.
+
+    Backlog of 5 (not 1) matches ``socketserver.TCPServer.request_queue_size``,
+    the depth ``HTTPServer`` itself would have bound with under the old
+    close-then-rebind implementation of :func:`capture_code` — this socket is
+    now handed to ``HTTPServer`` directly (never rebound), so the depth has to
+    be set here to stay equivalent. Matters in practice for the same reason
+    :func:`capture_code` already serves in a loop rather than answering a
+    single request: a browser can fire a prefetch (e.g. ``/favicon.ico``)
+    essentially back-to-back with the real OAuth redirect, and a backlog of 1
+    leaves less room to queue a second pending connection while the first is
+    being accepted.
+    """
+    for port in CANDIDATE_PORTS:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.bind(("127.0.0.1", port))
+            sock.listen(5)
+            return sock
+        except OSError:
+            sock.close()
+            continue
+    return None
+
+
+def capture_code(server_socket: socket.socket, expected_state: str) -> str:
+    """Block until the browser redirects back, validate state, return the code.
+
+    Renders a success page so the browser tab can be closed by the user. The
+    already-bound, already-listening ``server_socket`` (put in listen state by
+    :func:`bind_loopback` before the browser was ever opened) is handed straight
+    to the ``HTTPServer`` — it is never closed and rebound. Closing + rebinding
+    used to leave a window in which nothing was listening on the port, with no
+    signal that the replacement server was ready, so the browser's OAuth
+    callback could arrive during that gap (and tests had to paper over it with
+    sleeps). Reusing the live socket keeps the port continuously accepting from
+    the moment ``bind_loopback`` returned.
+
+    Serves requests in a loop (bounded by :data:`LOGIN_TIMEOUT_SECONDS` in
+    total) rather than a single ``handle_request()`` call — a browser routinely
+    fires an unrelated request at the loopback port before the real OAuth
+    redirect (e.g. a ``/favicon.ico`` prefetch for the success page's tab);
+    handling exactly one request would let that prefetch consume the only
+    request the server ever answers and report a spurious "Login timed out"
+    a moment before the real callback arrives. Only a request to
+    :data:`LOOPBACK_PATH` ever populates ``result``, so every other path is
+    404'd and the server keeps waiting.
+    """
+    result: dict[str, str] = {}
+
+    class _Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A002 — http.server API
+            pass  # suppress default stderr logging
+
+        def do_GET(self) -> None:  # noqa: N802 — must match BaseHTTPRequestHandler
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != LOOPBACK_PATH:
+                # Not the OAuth callback (a browser prefetch, e.g.
+                # /favicon.ico) — 404 it and keep serving; never populates
+                # `result`, so it can't be mistaken for the real redirect.
+                self.send_error(404)
+                return
+            params = urllib.parse.parse_qs(parsed.query)
+            code = (params.get("code") or [""])[0]
+            state = (params.get("state") or [""])[0]
+
+            if not secrets.compare_digest(state, expected_state):
+                result["error"] = "state_mismatch"
+                self.send_error(400, "state mismatch")
+                return
+            if not code:
+                result["error"] = "missing_code"
+                self.send_error(400, "missing code")
+                return
+
+            result["code"] = code
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(
+                b"<html><body>"
+                b"<h2>simulo: sign-in complete</h2>"
+                b"<p>You may close this window.</p>"
+                b"</body></html>"
+            )
+
+    host, port = server_socket.getsockname()
+    # bind_and_activate=False skips HTTPServer's own bind()/listen(); we then
+    # swap in the socket bind_loopback() already bound and put in listen state,
+    # so the listener is continuously up (no close-then-rebind gap). server_close
+    # at the end closes this socket — the caller hands ownership over.
+    httpd = http.server.HTTPServer((host, port), _Handler, bind_and_activate=False)
+    httpd.socket.close()  # discard the unused fresh socket HTTPServer created in __init__
+    httpd.socket = server_socket
+
+    deadline = time.monotonic() + LOGIN_TIMEOUT_SECONDS
+    while "code" not in result and "error" not in result:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        httpd.timeout = remaining
+        httpd.handle_request()
+    httpd.server_close()
+
+    if "error" in result:
+        raise LoginError(f"Login failed: {result['error']}")
+    if "code" not in result:
+        raise LoginError("Login timed out. Run `simulo login` again.")
+    return result["code"]
+
+
+# ---------------------------------------------------------------------------
+# Manual fallback (headless / remote-SSH environments)
+# ---------------------------------------------------------------------------
+
+
+def manual_fallback_code(authorize_url: str, expected_state: str, *, prompt: Any = input, echo: Any = print) -> str:
+    """Print the authorize URL; prompt the user to paste back the code + fingerprint.
+
+    The out-of-band ``/cli-callback`` page shows the code and the first 8
+    characters of the state as a fingerprint the user must confirm here — the
+    CLI never prints its own expected fingerprint (that would collapse the
+    two-channel verification into one channel).
+    """
+    echo(
+        "\nCould not open a local browser callback port.\n"
+        "Open this URL in a browser on another machine:\n\n"
+        f"  {authorize_url}\n\n"
+        "After signing in, the page will display a short code and an 8-character\n"
+        "state fingerprint. Paste both below.\n"
+    )
+    code = str(prompt("Paste the code: ")).strip()
+    entered_fingerprint = str(prompt("Enter the 8-character fingerprint shown on the page: ")).strip()
+
+    state_fingerprint = expected_state[:8]
+    if not secrets.compare_digest(entered_fingerprint, state_fingerprint):
+        raise LoginError("Login failed: state mismatch")
+    return code
+
+
+# ---------------------------------------------------------------------------
+# Orchestration
+# ---------------------------------------------------------------------------
+
+
+def _build_authorize_url(settings: config.LoginSettings, *, redirect_uri: str, state: str, challenge: str) -> str:
+    return f"{settings.cognito_hosted_ui}/oauth2/authorize?" + urllib.parse.urlencode(
+        {
+            "client_id": settings.cli_app_client_id,
+            "response_type": "code",
+            "scope": "openid email profile",
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+        }
+    )
+
+
+def perform_login(
+    *,
+    settings: Optional[config.LoginSettings] = None,
+    open_browser: Any = webbrowser.open,
+) -> dict[str, Any]:
+    """Run the full PKCE loopback (or manual-fallback) login flow.
+
+    On success, writes ``~/.simulo/credentials`` (0600) and returns the saved
+    dict. Raises :class:`LoginError` on any failure (empty client id, state
+    mismatch, rejected code, malformed response).
+    """
+    resolved = settings or config.resolve_login_settings()
+
+    # Guard: an empty client id causes a silent 401 after the full OAuth
+    # round-trip (Cognito accepts a blank client_id but the control plane
+    # rejects the token) — fail fast with a clear message instead.
+    if not resolved.cli_app_client_id:
+        raise LoginError(
+            "SIMULO_CLI_APP_CLIENT_ID is not set.\n"
+            "  For staging:  SIMULO_ENV=staging simulo login\n"
+            "  For dev:      set SIMULO_CLI_APP_CLIENT_ID=<client-id>"
+        )
+
+    verifier, challenge = generate_pkce()
+    state = secrets.token_urlsafe(32)
+
+    loopback = bind_loopback()
+    if loopback is not None:
+        _, port = loopback.getsockname()
+        redirect_uri = f"http://127.0.0.1:{port}{LOOPBACK_PATH}"
+    else:
+        redirect_uri = f"{resolved.console_base_url}{LOOPBACK_PATH}"
+
+    authorize_url = _build_authorize_url(resolved, redirect_uri=redirect_uri, state=state, challenge=challenge)
+
+    if loopback is not None:
+        print("Opening your browser to sign in...")
+        open_browser(authorize_url)
+        code = capture_code(loopback, state)
+    else:
+        code = manual_fallback_code(authorize_url, state)
+
+    # code_verifier is intentionally NOT logged; it must never appear in any log.
+    try:
+        response = http_client.request_json(
+            "POST",
+            resolved.api_base_url.rstrip("/") + CLI_CALLBACK_PATH,
+            json_body={"code": code, "code_verifier": verifier, "redirect_uri": redirect_uri},
+            unavailable_hint="Check SIMULO_API_URL / SIMULO_ENV.",
+        )
+    except http_client.HttpHTTPError as exc:
+        raise LoginError("Login failed: the control plane rejected the sign-in callback. Try again.") from exc
+    except http_client.HttpUnavailable as exc:
+        raise LoginError("Login failed: Cannot reach the Simulo platform. Check SIMULO_API_URL / SIMULO_ENV.") from exc
+
+    if not isinstance(response, dict):
+        raise LoginError("Login failed: malformed response from the control plane.")
+    required = ("access_token", "refresh_token", "expires_at", "user_email", "organization_id")
+    missing = [field for field in required if field not in response]
+    if missing:
+        raise LoginError(f"Login failed: response missing field(s) {missing}.")
+    organization_id = _require_canonical_organization_id(response["organization_id"])
+
+    # Explicit mapping — never save the raw response dict. Note: the response
+    # uses 'organization_id'; the credentials file uses 'active_organization_id'.
+    creds: dict[str, Any] = {
+        "version": 1,
+        "access_token": response["access_token"],
+        "refresh_token": response["refresh_token"],
+        "expires_at": response["expires_at"],
+        "user_email": response["user_email"],
+        "active_organization_id": organization_id,
+        "api_base_url": resolved.api_base_url,
+        "console_base_url": resolved.console_base_url,
+    }
+    save_credentials(creds)
+    return creds

simulo/_client/mode.py

@@ -0,0 +1,29 @@
+"""Execution mode for the thin client, driven by the ``SIMULO_MODE`` env var.
+
+A single mode-aware package serves two roles:
+
+* ``discovery`` — *submit*: import the user app to harvest metadata and **write
+  the package** (manifest + source bundle) WITHOUT running any job body or
+  resolving heavy imports (``torch`` / Isaac / …). This is the only thing the user
+  does locally (``simulo run app.py``, the canonical — and only — submit command).
+* ``execution`` — *execute*: the ``simulo-backend`` runner imports the packaged
+  app to actually run a job body; ``runtime.imports()`` performs real imports.
+
+``discovery`` is the **default** so any bare ``import`` of a user app stays
+torch-free unless told otherwise; ``simulo run`` submits on that default.
+Execution is always set *explicitly* by the backend runner (``simulo-backend
+run-package``), which is the sole executor — so defaulting to the torch-free
+submit path can never mis-train.
+"""
+
+import os
+
+DISCOVERY = "discovery"
+EXECUTION = "execution"
+
+_ENV_VAR = "SIMULO_MODE"
+
+
+def current_mode() -> str:
+    """Return the active mode from ``SIMULO_MODE`` (defaults to ``discovery``)."""
+    return os.environ.get(_ENV_VAR, DISCOVERY)

simulo/_client/outputs.py

@@ -0,0 +1,116 @@
+"""Execution-time job-output registration — the real ``simulo.save_output``.
+
+This module is the **execution half** of the ``simulo.save_output`` lazy
+surface (the tier-2 declaration described in
+:mod:`simulo.interfaces.platform.outputs`). The name resolves mode-aware,
+exactly like the learning names (the thin client's internal learning module):
+
+* **discovery** (submit, the default) — ``simulo.save_output`` resolves to an
+  inert internal ``Stub``. Job bodies never execute at submit,
+  so the only way the name is touched is a module-level call in a user app —
+  which stays harmless and registers nothing, exactly like a module-level
+  ``simulo.Scene(...)``. Discovery therefore never needs — and never imports —
+  the backend registry, keeping ``import simulo`` torch-free and backend-free.
+* **execution** (the ``simulo-backend`` runner on a worker) — the name resolves
+  to :func:`save_output` below, which validates through the contract's
+  :class:`~simulo.interfaces.platform.outputs.Output` and registers into
+  the process-local ``simulo.outputs`` registry the runner drains to
+  ``--outputs-out`` once the job body returns.
+
+The registry import happens **inside** :func:`save_output`, at call time:
+this module itself stays importable in a submit-only environment (the
+``TYPE_CHECKING`` alias in ``simulo/__init__.py`` names it, and the test suite
+imports it directly), while ``simulo.outputs`` ships with ``simulo-backend``
+and exists only where jobs execute.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Union
+
+from simulo.interfaces.platform import Output, OutputKind
+
+
+def save_output(
+    name: str,
+    path: Union[str, bytes, "os.PathLike[str]", "os.PathLike[bytes]"],
+    kind: Union[OutputKind, str] = OutputKind.FILE,
+) -> bool:
+    """Register metadata for a file produced while this job is running.
+
+    This validates the name, path, and kind, then records them in the running
+    job. Returning successfully makes eligible registrations available to the
+    worker for upload; a file becomes available through ``simulo outputs``
+    only after the upload is persisted. A cancelled, timed-out, crashed, or
+    otherwise failed run does not reach the successful registry drain, and a
+    refused or unsuccessful upload can also leave a registration undelivered.
+    Use a named :class:`simulo.Volume` instead when another job needs shared
+    durable files.
+
+    Args:
+        name: The registration's logical filename. It must be one safe
+            filename, never a path: separators, control characters, dots-only
+            tokens, empty values, and over-length names are rejected with
+            ``ValueError``.
+        path: Filesystem path of the produced file. ``str``, ``bytes``, or any
+            ``os.PathLike`` (a ``pathlib.Path`` works); bytes-ish values are
+            ``os.fsdecode``-d, so a real non-UTF-8 filename registers fine.
+            Validated for usability: type, length, non-empty, and no NUL.
+        kind: What the output is — an
+            :class:`~simulo.interfaces.platform.enums.OutputKind` or its wire
+            string (e.g. ``"report"``, ``"dataset"``). Defaults to
+            :attr:`~simulo.interfaces.platform.enums.OutputKind.FILE`, the
+            kind for a general produced file.
+
+    Returns:
+        ``True`` when the registration was kept; ``False`` when it was dropped
+        because the run already registered 1000 files. Register final output,
+        not a new scratch file on every simulation step.
+
+    Raises:
+        ValueError: ``name`` is not a safe single filename, ``path`` is not
+            usable as a path, or ``kind`` is not a known output kind — all
+            surfaced at the call site before anything is registered.
+        ModuleNotFoundError: The job runtime is missing a required dependency.
+        RuntimeError: Called outside a supported job execution context.
+    """
+    if isinstance(path, (bytes, os.PathLike)):
+        # ``os.fsdecode`` maps a bytes / PathLike path to the exact ``str`` the
+        # registry round-trips (surrogateescape — a real non-UTF-8 filename
+        # stays registrable). Any OTHER type falls through untouched so the
+        # contract's validator raises its documented ``ValueError``.
+        #
+        # This call is the one place an argument problem could escape as
+        # something other than that ``ValueError``: a ``PathLike`` whose
+        # ``__fspath__`` returns non-str/bytes raises ``TypeError``, and
+        # anything ``__fspath__`` itself raises (``OSError``, ``KeyError``, …)
+        # propagates verbatim. Both mean precisely what the contract calls an
+        # unusable ``path``, so both are re-raised as the contract's
+        # ``ValueError`` with the original chained on ``__cause__``: a caller
+        # who wrapped an optional registration in ``except ValueError`` must
+        # not be blown past by an ``__fspath__`` quirk.
+        try:
+            path = os.fsdecode(path)
+        except Exception as exc:
+            raise ValueError(
+                f"simulo.save_output() could not read a filesystem path out of the {type(path).__name__} "
+                f"passed as path: {exc}"
+            ) from exc
+    output = Output(name=name, path=path, kind=kind)  # type: ignore[arg-type]
+    try:
+        outputs = importlib.import_module("simulo.outputs")
+    except ModuleNotFoundError as exc:
+        if exc.name != "simulo.outputs":
+            # ``simulo.outputs`` is present and IT failed to import something.
+            # Relabelling that as "simulo-backend is not installed here" sends
+            # the reader hunting a missing distribution that is in fact
+            # installed; the real missing name is already in this exception.
+            raise
+        raise RuntimeError(
+            "simulo.save_output() needs the simulo-backend job registry (simulo.outputs), which is "
+            "not installed here. It is called from a job body running on the platform; at submit the "
+            "name resolves to an inert stub and this code is never reached."
+        ) from exc
+    return bool(outputs.register(output))