urun-cli 0.7.5__tar.gz → 0.7.6__tar.gz

{urun_cli-0.7.5 → urun_cli-0.7.6}/CHANGELOG.md

@@ -1,3 +1,24 @@
+## Unreleased
+
+- Security (ENG-570 / pentest urun-cli-01, mirrored in urun-python
+  `urun/core/store/repo.py`): `store.repo(...)` specs parsed from untrusted
+  app source are validated before any git call. The `@<ref>` pin must be a
+  full 40-hex SHA or a plain refname over `[A-Za-z0-9._/-]` (never a leading
+  `-`, never `=`), and the spec head may not start with `-`. A crafted
+  `@--upload-pack=<payload>` tail on a local-path spec made git EXECUTE the
+  payload on the deployer's machine.
+- Security (ENG-570 / pentest urun-cli-02): the `urun dev --attach` loopback
+  token endpoint reflects `Access-Control-Allow-Origin` only for loopback
+  browser origins (any port) in dev mode; a remote page's Origin gets 403
+  and no CORS headers.
+- Security (ENG-570 / pentest urun-cli-03): `urun compat` no longer hands the
+  raw org API key plus the developer's full exported environment to a
+  PATH-resolved `urun-openai`. The compat child env is the frontend scrub
+  allowlist plus the compat credential keys (explicit env wins per key are
+  forwarded through the credentials dict), and the PATH lane is refused
+  while credentials are handed over — explicit `URUN_OPENAI_PROXY_BIN` or
+  the vendored binary only.
+
 ## 0.7.3
 
 - `urun serve --urun-wheel <version>` — pin a deploy to a specific urun wheel

{urun_cli-0.7.5 → urun_cli-0.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.7.5
+Version: 0.7.6
 Summary: End-user CLI for deploying apps to urun
 Project-URL: Homepage, https://urun.sh
 Project-URL: Repository, https://github.com/urun-sh/urun-cli

{urun_cli-0.7.5 → urun_cli-0.7.6}/pyproject.toml

@@ -20,7 +20,7 @@ name = "urun-cli"
 # so every merge remains on the already-published version until this value is
 # advanced. Wiring semantic-release into CI remains separate work; this patch
 # bump is the minimal release unblock (post-v0.6.3 fixes + the Rust feature minor).
-version = "0.7.5"
+version = "0.7.6"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/cli.py

@@ -361,6 +361,8 @@ def main(argv: list[str] | None = None) -> int:
             return fleet_command(args)
         if args.command == "scratch":
             return scratch_command(args)
+        if args.command == "reserve":
+            return reserve_command(args)
         parser.print_help()
         return 2
     except UrunError as exc:
@@ -623,6 +625,61 @@ def add_inverted_noun_parsers(sub: argparse._SubParsersAction) -> None:
     add_activity_parsers(sub)
     add_failure_group_parsers(sub)
     add_git_installation_parsers(sub)
+    add_reserve_parser(sub)
+
+
+def add_reserve_parser(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "reserve",
+        help="Reserve a GPU node for one app (operator; app-exclusive nodes)",
+        description=(
+            "App-exclusive nodes (operator verb): reserve a GPUWorkerClaim "
+            "for ONE app so the node serves only it — foreign serving "
+            "residents drain, foreign scratch residents are reaped, and "
+            "fresh demand for other apps mints fresh capacity instead of "
+            "squatting the reserved node. Writes the SAME "
+            "urun.sh/reserved-for (+ urun.sh/pin-until with --until) "
+            "annotations the control plane's reservation mechanism reads, "
+            "through its sanctioned /node-reservations surface.\n\n"
+            "Usage: urun reserve <claim> --app <app_id>[/<fn>] "
+            "[--until <RFC3339>] --context <ctx> | urun reserve release <claim> "
+            "--context <ctx> | urun reserve list [--context <ctx>]\n\n"
+            "--context is REQUIRED for reserve/release (a reservation is a "
+            "live cluster write; be looking at the cluster you write to). "
+            "A bare reservation holds at most 8h; pass --until for an "
+            "explicit bounded TTL (also capped at 8h, the pin's clamp)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    reserve_sub = parser.add_subparsers(dest="reserve_command")
+
+    set_p = reserve_sub.add_parser(
+        "set", help="Reserve a claim for an app (implicit: urun reserve <claim> --app …)"
+    )
+    set_p.add_argument(
+        "claim", help="GPUWorkerClaim name (e.g. node-autoscaler-rtx6000-ba6262d689)"
+    )
+    set_p.add_argument(
+        "--app", required=True, help="<app_id>[/<fn>] the node will serve exclusively"
+    )
+    set_p.add_argument("--until", default=None, help="RFC3339 deadline (bounded by the 8h pin cap)")
+    _add_reserve_cluster_args(set_p)
+
+    release_p = reserve_sub.add_parser("release", help="Release a claim's reservation (idempotent)")
+    release_p.add_argument("claim")
+    _add_reserve_cluster_args(release_p)
+
+    list_p = reserve_sub.add_parser("list", help="List every reserved claim")
+    _add_reserve_cluster_args(list_p)
+
+
+def _add_reserve_cluster_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--context",
+        default=None,
+        help="kubectl context (REQUIRED for set/release; the active context for list)",
+    )
+    parser.add_argument("--namespace", default="urun", help="Namespace (default: urun)")
 
 
 def add_session_parsers(sub: argparse._SubParsersAction) -> None:
@@ -1414,7 +1471,7 @@ def add_org_parser(sub: argparse._SubParsersAction) -> None:
             "cap back to unlimited."
         ),
     )
-    limits_parser.add_argument("--monthly-usd-cap", dest="monthly_usd_cap", type=float)
+    limits_parser.add_argument("--monthly-credit-cap", dest="monthly_credit_cap", type=int)
     limits_parser.add_argument(
         "--max-concurrent-sessions", dest="max_concurrent_sessions", type=int
     )
@@ -1423,7 +1480,7 @@ def add_org_parser(sub: argparse._SubParsersAction) -> None:
     limits_parser.add_argument(
         "--clear",
         action="append",
-        choices=("monthly_usd_cap", "max_concurrent_sessions", "max_gpu_units"),
+        choices=("monthly_credit_cap", "max_concurrent_sessions", "max_gpu_units"),
         help="Cap(s) to reset to unlimited (repeatable)",
     )
     # defer_to_parent: `org` defines these same flags, so this child must not
@@ -1956,7 +2013,7 @@ def org_identity_lines(config: dict[str, Any], resolved: ResolvedCredentials) ->
 def org_set_limits(args: argparse.Namespace) -> int:
     payload: dict[str, Any] = {}
     for key in (
-        "monthly_usd_cap",
+        "monthly_credit_cap",
         "max_concurrent_sessions",
         "max_gpu_units",
         "alert_threshold_pct",
@@ -1968,7 +2025,7 @@ def org_set_limits(args: argparse.Namespace) -> int:
         payload["clear"] = args.clear
     if not payload:
         raise UrunError(
-            "nothing to set; pass at least one of --monthly-usd-cap, "
+            "nothing to set; pass at least one of --monthly-credit-cap, "
             "--max-concurrent-sessions, --max-gpu-units, --alert-threshold-pct, --clear"
         )
     return print_or_table(_client(args).set_org_limits(payload), args, "org limits")
@@ -4107,6 +4164,40 @@ def _builders_resolve_command(args: argparse.Namespace, client: ApiClient) -> in
     return print_or_table(response, args, "builder")
 
 
+def reserve_command(args: argparse.Namespace) -> int:
+    from .reserve import list_reservations, release, reserve
+
+    command = getattr(args, "reserve_command", None)
+    context = getattr(args, "context", None)
+    namespace = getattr(args, "namespace", None) or "urun"
+    if command == "list":
+        rows = list_reservations(context, namespace)
+        reservations = rows.get("reservations") or []
+        if not reservations:
+            print("no reserved claims")
+            return 0
+        for row in reservations:
+            until = (
+                row.get("pin_until") or f"bare (≤{int((row.get('max_hold_s') or 0) / 3600)}h hold)"
+            )
+            print(
+                f"{row.get('claim')}  reserved-for={row.get('reserved_for')}  until={until}  phase={row.get('phase') or '?'}"
+            )
+        return 0
+    if command == "release":
+        state = release(context, namespace, args.claim)
+        print(f"released {args.claim} (was_reserved={state.get('was_reserved')})")
+        return 0
+    if command == "set":
+        state = reserve(context, namespace, args.claim, args.app, getattr(args, "until", None))
+        until = state.get("pin_until") or "bare (bounded at the 8h hold cap)"
+        print(f"reserved {state.get('claim')} for {state.get('reserved_for')} (until={until})")
+        print("the node's scheduler applies it on its next poll tick (~15s)")
+        return 0
+    print("usage: urun reserve {set|release|list}", file=sys.stderr)
+    return 2
+
+
 def node_command(args: argparse.Namespace) -> int:
     target = getattr(args, "node_command", None)
     if target == "ls":
@@ -4584,6 +4675,39 @@ def _app_payload(response: dict[str, Any]) -> dict[str, Any]:
     return app
 
 
+def _actual_release_entries(app: dict[str, Any]) -> list[dict[str, Any]]:
+    """Presence-derived actual-release rollup entries, oldest planes tolerated.
+
+    The plane (migration 20270319000000) reports `actual_release_ids` as a list
+    of {release_id, manifest_hash, pods} for the fresh ready pods actually
+    serving the function. Older planes omit the field entirely and scale-to-zero
+    reports JSON null; both degrade to an empty list so the rendered output is
+    exactly what it is today.
+    """
+    entries = app.get("actual_release_ids")
+    if entries is None:
+        return []
+    if not isinstance(entries, list) or any(not isinstance(entry, dict) for entry in entries):
+        raise UrunError("server returned invalid actual_release_ids payload")
+    return entries
+
+
+def _actual_release_label(entry: dict[str, Any]) -> str:
+    return _short_hash(entry.get("manifest_hash") or entry.get("release_id"))
+
+
+def _pods_str(count: Any) -> str:
+    if _is_non_bool_int(count):
+        return f"{count} pod" if count == 1 else f"{count} pods"
+    return "? pods"
+
+
+def _actual_release_summary(entries: list[dict[str, Any]]) -> str:
+    return ", ".join(
+        f"{_actual_release_label(entry)} ({_pods_str(entry.get('pods'))})" for entry in entries
+    )
+
+
 def app_status(args: argparse.Namespace) -> int:
     api_url, api_key = resolve_api_credentials(args)
     environment = resolve_environment(args)
@@ -4618,8 +4742,15 @@ def app_status(args: argparse.Namespace) -> int:
         ("Compute", _coalesce_str(app.get("compute_shape"), "-")),
         ("GPU", _gpu_str(app)),
         ("Release", _short_hash(app.get("manifest_hash") or app.get("release_version"))),
-        ("Live sessions", _int_str(app.get("active_sessions"))),
     ]
+    # Desired vs actual: `Release` above is the DESIRED (promoted) release; the
+    # plane additionally reports which release the fresh ready pods are ACTUALLY
+    # serving (runtime_presence rollup). Absent on older planes and on
+    # scale-to-zero — in both cases the output stays exactly what it is today.
+    actual_entries = _actual_release_entries(app)
+    if actual_entries:
+        fields.append(("Release (actual)", _actual_release_summary(actual_entries)))
+    fields.append(("Live sessions", _int_str(app.get("active_sessions"))))
     health_rows = response.get("runtime_health")
     if isinstance(health_rows, list):
         for health_value in health_rows:
@@ -4643,6 +4774,22 @@ def app_status(args: argparse.Namespace) -> int:
     width = max(len(label) for label, _ in fields)
     for label, value in fields:
         print(f"{label.rjust(width)}: {value}")
+    # The displayed `Status` value stays untouched (scripted consumers gate on
+    # it); the mismatch is surfaced as an explicit warning line instead.
+    if app.get("release_mismatch") is True:
+        current_release_id = app.get("current_release_id")
+        stale_entries = [
+            entry
+            for entry in actual_entries
+            if entry.get("release_id") is not None and entry.get("release_id") != current_release_id
+        ]
+        stale_summary = _actual_release_summary(stale_entries) or "unknown"
+        explanation = (
+            'status "ready" reflects warm capacity, not materialization of the desired release'
+            if _coalesce_str(app.get("status"), "") == _DISPLAY_READY
+            else "the desired release is not yet materialized on these pods"
+        )
+        print(f"WARNING: pods still running previous release {stale_summary} — {explanation}")
     return 0
 
 
@@ -5989,14 +6136,33 @@ def resolve_compat_credentials(app_flag: str | None = None) -> dict[str, str]:
     only DERIVED (via :func:`sdk_base_url`) when the caller did not set it:
     deriving eagerly would raise on a custom-path api_url even when the caller
     already supplied the exact override :func:`sdk_base_url`'s error recommends.
+
+    SECURITY (pentest urun-cli-03): the compat child env is the frontend scrub
+    allowlist (:func:`urun.frontend_launch.frontend_child_env`) plus these
+    credential keys — NEVER the developer's full exported
+    environment, and the PATH binary lane is refused. The env-wins-per-key
+    contract is preserved by forwarding explicit URUN_BASE_URL / URUN_ORG_ID
+    through this dict.
     """
     args = argparse.Namespace(api_key=None, api_url=None, gateway_url=None)
     api_url, api_key = resolve_api_credentials(args)
     credentials = {"URUN_API_KEY": api_key}
-    if not string_value(os.environ.get("URUN_BASE_URL")):
+    explicit_base_url = string_value(os.environ.get("URUN_BASE_URL"))
+    if explicit_base_url:
+        # SECURITY (pentest urun-cli-03): the compat child env is SCRUBBED
+        # (run_proxy builds it from frontend_child_env), so an explicit
+        # URUN_BASE_URL rides to the child through the credentials dict —
+        # the same env-wins-per-key contract as before the scrub.
+        credentials["URUN_BASE_URL"] = explicit_base_url
+    else:
         credentials["URUN_BASE_URL"] = sdk_base_url(api_url)
     saved = load_credentials()
-    if api_key == string_value(saved.get("api_key")):
+    explicit_org_id = string_value(os.environ.get("URUN_ORG_ID"))
+    if explicit_org_id:
+        # Same env-wins-per-key contract as URUN_BASE_URL above: the scrubbed
+        # child env would otherwise swallow an explicit URUN_ORG_ID.
+        credentials["URUN_ORG_ID"] = explicit_org_id
+    elif api_key == string_value(saved.get("api_key")):
         org_id = string_value(saved.get("org_id"))
         if org_id:
             credentials["URUN_ORG_ID"] = org_id

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/client_tokens.py

@@ -29,11 +29,13 @@ treats a CLI launch and a hosted token route identically).
 
 from __future__ import annotations
 
+import ipaddress
 import json
 import re
 import sys
 import threading
 import time
+import urllib.parse
 from collections.abc import Callable
 from dataclasses import dataclass
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -91,6 +93,31 @@ def is_loopback_host(host: str) -> bool:
     return canonical_demo_host(host) in _LOOPBACK_HOSTS
 
 
+def browser_origin_is_loopback(origin: str) -> bool:
+    """Whether a browser ``Origin`` names THIS machine (loopback host, any port).
+
+    ``http://127.0.0.1:5173``, ``http://localhost:3000``, any ``127.x.x.x``
+    address and ``*.localhost`` subdomains (browsers resolve those to loopback,
+    RFC 6761) are pages on this machine; ``https://proxy.example`` or a LAN
+    address is not. Dev-mode CORS reflection accepts ONLY these (pentest
+    urun-cli-02): reflecting an arbitrary Origin handed the live, silently
+    re-minting session token to any website open in the developer's browser,
+    which needs only a loopback port scan to read it cross-origin.
+    """
+    try:
+        host = (urllib.parse.urlsplit(origin).hostname or "").lower().strip("[]")
+    except ValueError:
+        return False
+    if not host:
+        return False
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
 def require_loopback_demo_host(host: str) -> str:
     """The CANONICAL demo host, or a LOUD refusal for anything routable.
 
@@ -379,19 +406,20 @@ class _TokenRequestHandler(BaseHTTPRequestHandler):
     does and reads as a stronger guarantee than exists:
 
     * ``/token`` — demo callers must present an allowed Origin. Dev callers
-      may present any Origin because the endpoint remains loopback-bound and a
-      developer may attach through any browser or proxy. A caller that sends
-      NO Origin is also served, because the hosted token route this mirrors is
-      fetched by server-side code, which sends none. Any local process can
-      therefore read a token, which is why the socket is bound to loopback and
-      only loopback (see ``require_loopback_demo_host``).
+      may present any LOOPBACK Origin (any port): a developer may attach
+      through any page served on this machine. Reflecting an arbitrary
+      non-loopback Origin is refused (403) — pentest urun-cli-02: an
+      arbitrary website open in the browser could otherwise read the live,
+      silently re-minting token cross-origin with a plain loopback port
+      scan. A caller that sends NO Origin is also served, because the
+      hosted token route this mirrors is fetched by server-side code, which
+      sends none. Any local process can therefore read a token, which is
+      why the socket is bound to loopback and only loopback (see
+      ``require_loopback_demo_host``).
     * ``/events`` — demo callers must present an allowed Origin, while dev
-      callers may present any Origin for the same reason as ``/token``. An
-      absent Origin is always refused because this route is browser-only.
-
-    The Origin check is a browser-context control and nothing more: outside a
-    browser the header is caller-controlled, and the permitted origins are a
-    readable claim inside the token itself. What actually bounds this token is
+      callers may present any LOOPBACK Origin for the same reason as
+      ``/token``. An absent Origin is always refused because this route is
+      browser-only.
     ``allowed_functions``, its expiry, and ``max_session_s``.
     """
 
@@ -403,7 +431,11 @@ class _TokenRequestHandler(BaseHTTPRequestHandler):
         if origin is None:
             return None
         if self.server.unrestricted_browser_origins:
-            return origin
+            # SECURITY (pentest urun-cli-02): dev reflects ONLY loopback
+            # browser origins (any port) — pages on THIS machine. Reflecting
+            # an arbitrary Origin handed the live, silently re-minting token
+            # to any website in the browser; a remote page gets 403.
+            return origin if browser_origin_is_loopback(origin) else ""
         return origin if origin in self.server.allowed_origins else ""
 
     def _reject_disallowed_origin(self, origin: str | None) -> bool:

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/dev.py

@@ -1439,7 +1439,7 @@ def _maybe_launch_frontend(
         "frontend | ",
         "browser auth: scoped client token "
         f"(functions: {', '.join(launch.allowed_functions)}; "
-        "origins: unrestricted (dev only); "
+        "origins: loopback browser origins only (dev only); "
         f"max session: {f'{launch.max_session_s}s' if launch.max_session_s else 'uncapped (ends with the CLI)'})",
     )
     mux.line(

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/openai_proxy_bin.py

@@ -30,11 +30,14 @@ Resolution is fail-loud, one canonical order, no silent fallback:
 1. ``URUN_OPENAI_PROXY_BIN`` (explicit path — always wins, must exist);
 2. the vendored platform binary shipped inside this package
    (``src/urun/_bin/urun-openai``);
-3. ``urun-openai`` on ``PATH`` (dev installs);
+3. ``urun-openai`` on ``PATH`` (dev installs) — refused whenever org
+   credentials are handed to the child (pentest urun-cli-03);
 4. a loud error naming all three lanes.
 
 A missing vendored binary falls through to PATH by design — that fall-through
-is part of the documented canonical order above, not a silent fallback. The
+is part of the documented canonical order above, not a silent fallback (the
+credential-carrying call is the exception: there the missing vendored binary
+fails LOUD rather than hand the org key to a PATH-resolved binary). The
 proxy's own session config (``URUN_BASE_URL`` / ``URUN_ORG_ID`` / ``URUN_APP``
 / ``URUN_JWT``) passes through the environment untouched.
 """
@@ -73,8 +76,20 @@ def vendored_proxy_binary() -> str | None:
     return str(path)
 
 
-def resolve_proxy_binary(env: Mapping[str, str] | None = None) -> str:
-    """The proxy binary path — explicit env override, else vendored, else PATH, else loud."""
+def resolve_proxy_binary(
+    env: Mapping[str, str] | None = None, *, allow_path_lane: bool = True
+) -> str:
+    """The proxy binary path — explicit env override, else vendored, else PATH.
+
+    ``allow_path_lane=False`` (used whenever credentials are handed to the
+    child) refuses the PATH lane: a repo-run dev script can plant a
+    ``urun-openai`` executable on the user's PATH (an ordinary file write
+    within its scrubbed powers) and capture the org API key the CLI injects —
+    exactly the capability the frontend env scrub removed from
+    repository-run processes (pentest urun-cli-03). The explicit
+    ``URUN_OPENAI_PROXY_BIN`` override and the package-vendored binary stay
+    allowed: those are operator-controlled, not attacker-placeable.
+    """
     environ = os.environ if env is None else env
     override = (environ.get(BIN_ENV) or "").strip()
     if override:
@@ -88,6 +103,14 @@ def resolve_proxy_binary(env: Mapping[str, str] | None = None) -> str:
     vendored = vendored_proxy_binary()
     if vendored:
         return vendored
+    if not allow_path_lane:
+        raise FileNotFoundError(
+            f"the {BIN_NAME!r} proxy binary cannot be resolved from PATH while "
+            "org credentials are handed to the child — a repo-run dev script "
+            "can plant a PATH entry and capture the key (pentest urun-cli-03). "
+            f"Set {BIN_ENV} to an explicit path or use a urun-cli build that "
+            f"vendors it at {VENDOR_DIR / BIN_NAME}"
+        )
     # Search the SUPPLIED environment's PATH — the same env the child launches
     # with. An env mapping without PATH has no PATH lane at all (loud below).
     found = shutil.which(BIN_NAME, path=environ.get("PATH", ""))
@@ -120,12 +143,34 @@ def run_proxy(
     them HERE, so they reach the child PROCESS-SCOPED — never shell-exported,
     never written to disk by this seam. Explicit env vars win over the store
     (the override lane); the store fills what the user did not set.
+
+    SECURITY (pentest urun-cli-03): when ``credentials`` are handed over, the
+    child env is NEVER the developer's full exported environment — it is the
+    frontend scrub allowlist (:func:`urun.frontend_launch.frontend_child_env`)
+    plus the credential keys only, and the PATH resolution lane is refused
+    (explicit ``URUN_OPENAI_PROXY_BIN`` path or vendored binary only). A
+    repo-run dev script could otherwise plant a ``urun-openai`` on PATH and
+    re-capture the raw org key and every exported secret (AWS_*,
+    GITHUB_TOKEN, ...) the scrub removed from repository-run processes.
     """
-    binary = resolve_proxy_binary(env)
-    base = dict(env) if env is not None else dict(os.environ)
     if credentials:
+        # Lazy import: frontend_launch pulls the API client surface; this
+        # module must stay importable standalone.
+        from .frontend_launch import frontend_child_env
+
+        base = frontend_child_env()
+        if env is not None:
+            # The CALLER env may be a full process environment — copy only the
+            # credential keys it sets (per-key env-wins), never the whole map.
+            for key in credentials:
+                if key in env:
+                    base[key] = env[key]
+        binary = resolve_proxy_binary(env, allow_path_lane=False)
         for key, value in credentials.items():
             base.setdefault(key, value)  # env overrides store, store fills gaps
+    else:
+        binary = resolve_proxy_binary(env)
+        base = dict(env) if env is not None else dict(os.environ)
     completed = subprocess.run(  # noqa: S603 — the resolved binary IS the product
         [binary, *args],
         env=base,

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/repo_deps.py

@@ -48,6 +48,62 @@ class RepoDepsError(Exception):
 
 _FULL_SHA_RE = re.compile(r"^[0-9a-fA-F]{40}$")
 
+#: A fetchable ref tail: a plain refname (branch / tag — a full 40-hex SHA is a
+#: subset of this charset). The FIRST character is alphanumeric so the ref can
+#: never start with ``-`` (git's parse-options would read it as an option) and
+#: the charset excludes ``=``, ``:``, ``@``, whitespace and every shell
+#: metacharacter. The ref rides as ONE argv element into
+#: ``git fetch --depth 1 origin <ref>``; for a local-path spec
+#: (``/abs/path`` / ``file://``) a ``--upload-pack=<payload>`` tail made git
+#: EXECUTE the payload on the deployer's machine (pentest urun-cli-01), so a
+#: ref that is not a plain refname is refused before any git call.
+_REFNAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+
+
+def _require_fetchable_ref(ref: str, spec: str) -> None:
+    """Refuse a ref git parse-options could read as an OPTION (ENG-570).
+
+    The spec is a string literal in UNTRUSTED app source and the ref tail
+    reaches git argv verbatim. A full 40-char commit SHA or a plain refname
+    over ``[A-Za-z0-9._/-]`` (never leading ``-``, never ``=``) is fetchable;
+    anything else — ``--upload-pack=<payload>`` above all — is option
+    injection and aborts the splice loudly.
+    """
+    if _FULL_SHA_RE.fullmatch(ref):
+        return
+    if _REFNAME_RE.fullmatch(ref):
+        # git-check-ref-format rules beyond the charset: no empty components
+        # (the ref tail can never contain "/", so ".." is the empty-
+        # component shape here), no trailing "." or ".lock". These would
+        # die at fetch time anyway; rejecting at parse time gives the bad
+        # pin a named, actionable error.
+        if ".." in ref or "//" in ref or "/." in ref or ref.endswith(".") or ref.endswith(".lock"):
+            raise RepoDepsError(
+                f"store.repo spec {spec!r}: invalid ref {ref!r} — not a valid "
+                "git refname (empty/dot-leading components or a trailing "
+                "'.lock'); fix the pin"
+            )
+        return
+    raise RepoDepsError(
+        f"store.repo spec {spec!r}: invalid ref {ref!r} — the pin must be a full "
+        "40-char commit SHA or a refname over [A-Za-z0-9._/-] not starting with "
+        "'-' (refuses git option injection)"
+    )
+
+
+def _require_fetchable_head(head: str, spec: str) -> None:
+    """Refuse a spec head (URL / local path) git would parse as an OPTION.
+
+    The head reaches ``git remote add origin <head>`` verbatim; a leading ``-``
+    turns the address into a git option instead of a remote.
+    """
+    if head.startswith("-"):
+        raise RepoDepsError(
+            f"store.repo spec {spec!r}: the repo URL/path may not start with '-' "
+            "(refuses git option injection)"
+        )
+
+
 #: Metadata files scanned for the upstream's own python deps, in priority order
 #: (mirrors urun-python ``repo._DEP_FILES``).
 _DEP_FILES = ("requirements.txt", "pyproject.toml", "setup.py")
@@ -92,10 +148,18 @@ def parse_repo_spec(spec: str) -> RepoSpec:
         # path separator and no scheme.
         if "/" not in maybe_ref and ":" not in maybe_ref:
             raw, ref = head, maybe_ref
+    # SECURITY (pentest urun-cli-01 / ENG-570): the spec is an attacker-
+    # controlled string literal in app source and BOTH halves reach git argv
+    # verbatim (``git remote add origin <head>`` / ``git fetch ... <ref>``).
+    # Refuse option-injection shapes before any git call.
+    if ref is not None:
+        _require_fetchable_ref(ref, spec)
+    _require_fetchable_head(raw, spec)
 
     # Local filesystem repo (absolute path or file:// URL).
     if raw.startswith("file://"):
         path = raw[len("file://") :]
+        _require_fetchable_head(path, spec)
         return RepoSpec(
             clone_url=path,
             ref=ref,

urun_cli-0.7.6/src/urun/reserve.py

@@ -0,0 +1,156 @@
+"""``urun reserve`` — the operator verb for app-exclusive nodes (lane 10).
+
+Reserves a GPUWorkerClaim for ONE app (`<app_id>[/<fn>]`), optionally
+bounded by a deadline, through the control plane's SANCTIONED surface
+(``POST``/``DELETE``/``GET /node-reservations`` on the urun-control-plane
+health port) — the same annotations the hand-rolled
+``kubectl annotate gpuworkerclaims … urun.sh/reserved-for=…`` path stamped,
+never a second mechanism.
+
+Dev/prod posture: unlike ``urun scratch`` (dev-only by context naming),
+reserving is FOR prod too — the whole point is guaranteeing a serving or
+training node to one app. The guard is therefore inverted: the operator's
+ACTIVE kubectl context is refused as a silent default for a WRITE; the
+context must be passed explicitly (``--context``), so a reservation can
+never land on a cluster the operator is not looking at. Listing takes the
+active context freely (a read).
+
+The verb shells kubectl port-forward to the control plane's health port —
+the same operator posture ``urun scratch`` already established (explicit
+context/namespace, kubectl-driven, no API-key surface involved).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .errors import UrunError
+
+#: The control-plane deployment whose health port carries the routes.
+CONTROL_PLANE_DEPLOYMENT = "urun-control-plane"
+#: The health server's port (URUN_CONTROL_HEALTH_PORT default).
+CONTROL_PLANE_PORT = 8080
+
+
+def _free_port() -> int:
+    import socket
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class _PortForward:
+    """A bounded kubectl port-forward to the control plane's health port."""
+
+    def __init__(self, context: str | None, namespace: str) -> None:
+        port = _free_port()
+        self.url = f"http://127.0.0.1:{port}"
+        cmd = ["kubectl"]
+        if context:
+            cmd += ["--context", context]
+        cmd += [
+            "-n",
+            namespace,
+            "port-forward",
+            f"deploy/{CONTROL_PLANE_DEPLOYMENT}",
+            f"{port}:{CONTROL_PLANE_PORT}",
+        ]
+        self.proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        # port-forward needs a moment; the request below retries transiently.
+        self._ready_deadline = time.monotonic() + 10.0
+
+    def request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        payload = json.dumps(body).encode("utf-8") if body is not None else None
+        last_exc: Exception | None = None
+        while time.monotonic() < self._ready_deadline + 20.0:
+            req = urllib.request.Request(
+                self.url + path,
+                data=payload,
+                method=method,
+                headers={"content-type": "application/json"} if payload else {},
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=30) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                # A defined API answer (404/409/4xx) is the SERVER speaking —
+                # relay its JSON body, never retry it away.
+                try:
+                    detail = json.loads(exc.read().decode("utf-8"))
+                except (ValueError, UnicodeDecodeError):
+                    detail = {}
+                message = str(detail.get("error") or detail.get("reason") or exc)
+                raise UrunError(message) from exc
+            except urllib.error.URLError as exc:
+                last_exc = exc
+                if self.proc.poll() is not None:
+                    raise UrunError("kubectl port-forward exited early") from exc
+                time.sleep(0.3)
+        raise UrunError(f"control-plane health port unreachable: {last_exc}")
+
+    def close(self) -> None:
+        self.proc.terminate()
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+
+
+def _connect(context: str | None, namespace: str) -> _PortForward:
+    # Refuse the ACTIVE context as a silent default for any WRITE; a read
+    # (list) takes it. main() passes context=None for reads only when the
+    # operator did not name one — the write paths resolve it themselves.
+    return _PortForward(context, namespace)
+
+
+def list_reservations(context: str | None, namespace: str) -> dict[str, Any]:
+    """GET /node-reservations — every reserved claim (scope, pin, phase)."""
+    pf = _connect(context, namespace)
+    try:
+        return pf.request("GET", "/node-reservations")
+    finally:
+        pf.close()
+
+
+def reserve(
+    context: str | None,
+    namespace: str,
+    claim: str,
+    app: str,
+    until: str | None,
+) -> dict[str, Any]:
+    """POST /node-reservations/{claim} — stamp urun.sh/reserved-for (+ pin)."""
+    if context is None:
+        raise UrunError(
+            "refusing to reserve against the ACTIVE kubectl context as a silent "
+            "default — pass --context explicitly (a reservation is a live "
+            "cluster write; be looking at the cluster you write to)"
+        )
+    pf = _connect(context, namespace)
+    try:
+        body: dict[str, Any] = {"app": app}
+        if until:
+            body["until"] = until
+        return pf.request("POST", f"/node-reservations/{claim}", body)
+    finally:
+        pf.close()
+
+
+def release(context: str | None, namespace: str, claim: str) -> dict[str, Any]:
+    """DELETE /node-reservations/{claim} — idempotent release."""
+    if context is None:
+        raise UrunError(
+            "refusing to release against the ACTIVE kubectl context as a silent "
+            "default — pass --context explicitly"
+        )
+    pf = _connect(context, namespace)
+    try:
+        return pf.request("DELETE", f"/node-reservations/{claim}")
+    finally:
+        pf.close()

{urun_cli-0.7.5 → urun_cli-0.7.6}/src/urun/serve.py

@@ -122,6 +122,25 @@ def _add_serve_model_args(parser: argparse.ArgumentParser) -> None:
             "to the spheron-pinned queue. Unpinned is the default and unchanged."
         ),
     )
+    # THE CPU DECLARATION'S PARSER HALF (owner design 2026-09-30, #353):
+    # the handler/shim/app halves shipped in #353 but this flag never did —
+    # argparse rejected `--cpu` before serve_model could honor it, so every
+    # shared-reconciler CPU row (phonon-2) died with "unrecognized
+    # arguments" (ENG-599, observed live on dev's ENG-584 sweep). Mirrors
+    # `urun scratch run`'s --cpu shape (cli.py); the handler validates the
+    # placement rules (CPU-only rows; --gpu <SKU> + --cpu is refused there).
+    parser.add_argument(
+        "--cpu",
+        dest="cpu",
+        type=int,
+        default=None,
+        metavar="N",
+        help=(
+            "CPU declaration for a gpu-less (CPU) placement: N cores "
+            "(shape cpu:N). Only valid with `--gpu none` or a CPU variant "
+            "— the shared reconciler's CPU rows pass it with --gpu none."
+        ),
+    )
     parser.add_argument(
         "--exo-class",
         dest="exo_class",
@@ -265,10 +284,32 @@ def serve_model(args: argparse.Namespace) -> int:
             "--cpu is the CPU declaration and only applies to a CPU (gpu-less) row; "
             "drop --cpu or resolve a CPU variant."
         )
+    # --cpu rides the generated shim's URUN_SERVE_CPUS channel, exactly like
+    # every other shim-transported pin (--warm, --urun-wheel, the provider pin,
+    # the EXO pin) — so it cannot be combined with --entrypoint: a local app is
+    # deployed as-is and nothing would carry the declaration (the pin would
+    # be a silent no-op; review finding round 1).
+    if requested_cpu is not None and getattr(args, "entrypoint", None):
+        raise UrunError(
+            "--cpu cannot be combined with --entrypoint. The CPU declaration "
+            "is set by the generated serve shim; a local --entrypoint app is "
+            "deployed as-is, so the declaration would silently do nothing. "
+            "Set cpus in your own app's @app.function(cpus=...) instead."
+        )
+    # `--cpu 0` / `--cpu -1` must fail from the args alone, before any catalog
+    # fetch — the shim's late rejection names the CATALOG ROW ("has no
+    # positive 'cpu' cores"), blaming the wrong input; the USER supplied the
+    # value (CodeRabbit finding).
+    if requested_cpu is not None and requested_cpu < 1:
+        raise UrunError(
+            f"--cpu must declare >= 1 core, got {requested_cpu}; "
+            "drop --cpu or pass a positive core count."
+        )
     client = resolve_catalog_client(args)
     rows = client.select_rows()
     requested_gpu = requested_gpu_raw
-    if requested_gpu == "none":
+    explicit_none_gpu = requested_gpu == "none"
+    if explicit_none_gpu:
         requested_gpu = None
     # PARSE THE PIN, THEN VALIDATE THE GPU, THEN THE REST FLOWS THROUGH (review:
     # Keegan, 2026-09-15). The provider rides IN the --gpu class because the
@@ -287,6 +328,11 @@ def serve_model(args: argparse.Namespace) -> int:
     #   non-enumerated-but-sufficient SKU is ALLOWED (with a warn) instead of rejected.
     #   "error" -> fail before deploy; "warn" -> proceed untuned (synthesize a deploy
     #   row pinned to the requested gpu_spec); enumerated SKU -> clean (resolve normally).
+    # - EXPLICIT `--gpu none` (CodeRabbit finding): the caller named the CPU
+    #   placement, so select the variant's gpu_spec-NULL row DIRECTLY — collapsing
+    #   it to an omitted --gpu would hand resolve_row "first placement", which
+    #   selects the GPU row first whenever a variant carries BOTH placements.
+    #   An omitted --gpu keeps the first-placement path untouched.
     if requested_gpu:
         level, message = validate_gpu_against_row(rows, model_id, variant, requested_gpu)
         if level == "error":
@@ -299,6 +345,27 @@ def serve_model(args: argparse.Namespace) -> int:
             row = dataclasses.replace(base, gpu_spec=requested_gpu)
         else:
             row = resolve_row(rows, model_id, variant, requested_gpu, searched=client.base_url)
+    elif explicit_none_gpu:
+        # Resolve the DEFAULT VARIANT first (CodeRabbit finding): `urun serve
+        # <id> --gpu none` arrives with variant=None, and filtering rows on
+        # `variant == None` matches nothing — resolve_row owns the
+        # first-listed-variant default AND the unknown-model/unknown-variant
+        # errors, so resolve through it, then filter the resolved variant's
+        # placements for the CPU row.
+        default_row = resolve_row(rows, model_id, variant, None, searched=client.base_url)
+        for_variant = [
+            r
+            for r in rows
+            if r.model_id == default_row.model_id and r.variant == default_row.variant
+        ]
+        cpu_rows = [r for r in for_variant if r.gpu_spec is None]
+        if not cpu_rows:
+            known = ", ".join(sorted(str(g) for g in {r.gpu_spec for r in for_variant})) or "(none)"
+            raise UrunError(
+                f"--gpu none names the CPU placement, but {default_row.model_id}:{default_row.variant} has "
+                f"no gpu_spec-NULL row. Available placements: {known}"
+            )
+        row = cpu_rows[0]
     else:
         row = resolve_row(rows, model_id, variant, None, searched=client.base_url)