@myvillage/cli 1.50.0 → 1.60.1

package/tools/preflight/README.md

@@ -0,0 +1,75 @@
+# MyVillage GameKit Bundle Preflight
+
+Inspects a Unity AssetBundle before submission and rejects it if it references any script outside the GameKit SDK allowlist.
+
+This script is invoked automatically by `myvillage deploy` for Unity bundles — you don't normally run it directly. It's also run server-side by the ed-platform as a defense-in-depth check.
+
+## Why it exists
+
+Unity AssetBundles can ship scenes, prefabs, and assets — but **not custom C# code**. Custom scripts must be types compiled into the M-UNI host app, which means they must come from the GameKit SDK. Preflight enforces that rule so unauthorized references are caught at upload time with a clear error, not as a confusing runtime crash on a player's device.
+
+## Install
+
+Requires **Python 3.9+** and **UnityPy 1.25.0** (specifically — newer versions may track Unity 6 deltas differently).
+
+```bash
+pip install -r requirements.txt
+```
+
+The CLI checks for `python3` and `UnityPy` automatically and prints install hints if either is missing.
+
+## Run directly (for debugging)
+
+```bash
+python3 preflight.py path/to/bundle.bundle path/to/allowlist.json
+```
+
+The allowlist JSON should match the shape returned by `GET /api/v1/gamekit/versions/<version>/allowlist`:
+
+```json
+{
+  "monoScripts": [
+    { "guid": "3a93ea8e08ef42e99b40236c4f7807a2", "path": "Runtime/IMissionHost.cs" }
+  ],
+  "assemblies": [
+    { "guid": "44b2f5a459b64410baeb0af8e1480847", "name": "MyVillage.GameKit" }
+  ]
+}
+```
+
+## Output
+
+JSON to stdout. Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0    | Bundle passes — no unauthorized references |
+| 1    | Bundle has violations (listed in JSON `violations` array) |
+| 2    | Preflight itself errored (missing files, parse error, missing UnityPy) |
+
+On pass:
+```json
+{
+  "status": "pass",
+  "bundle": "...",
+  "scriptsSeen": 12,
+  "violations": [],
+  "violationCount": 0
+}
+```
+
+On fail:
+```json
+{
+  "status": "fail",
+  "violations": [
+    {
+      "kind": "unauthorized_script",
+      "assembly": "Assembly-CSharp",
+      "namespace": "",
+      "className": "MyEnemyAI",
+      "reason": "Script references assembly 'Assembly-CSharp' which is not in the SDK allowlist..."
+    }
+  ]
+}
+```

package/tools/preflight/preflight.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""
+MyVillage GameKit bundle preflight.
+
+Scans a Unity AssetBundle (the output of Unity's AssetBundle build pipeline)
+for MonoScript references and Visual Scripting graph nodes that aren't in
+the GameKit SDK's allowlist. Also rejects bundles containing embedded
+.dll files.
+
+Used by:
+  - MyVillage CLI's `myvillage deploy` (catches violations pre-upload)
+  - ed-platform's game-submission.service (re-runs after upload — actual gate)
+
+Usage:
+    preflight.py <bundle_path> <allowlist_json_path>
+
+Output:
+    JSON to stdout. Exit code 0 on pass, 1 on violations, 2 on error.
+
+Allowlist JSON shape (matches GameKitVersion.guidAllowlist):
+    {
+      "monoScripts": [{ "guid": "...", "path": "..." }],
+      "assemblies":  [{ "guid": "...", "name": "MyVillage.GameKit" }],
+      "nodes":       ["Unity.VisualScripting.Branch", ...]   # M2+
+    }
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+def _emit(payload, exit_code):
+    print(json.dumps(payload, indent=2))
+    sys.exit(exit_code)
+
+
+def _error(message):
+    _emit({"status": "error", "error": message}, 2)
+
+
+# Unity ships these assemblies with the editor/runtime. References to types in
+# them are always allowed — they're trusted code that's already in the host.
+# Anything not on this list and not in the SDK allowlist gets rejected.
+BUILTIN_ASSEMBLY_PREFIXES = (
+    "UnityEngine",
+    "UnityEditor",
+    "Unity.",  # Unity.TextMeshPro, Unity.InputSystem, Unity.VisualScripting, etc.
+    "TextMeshPro",
+    "mscorlib",
+    "System",
+    "netstandard",
+)
+
+
+def _is_builtin_assembly(name: str) -> bool:
+    if not name:
+        return False
+    return any(name == p or name.startswith(p + ".") or name.startswith(p) for p in BUILTIN_ASSEMBLY_PREFIXES)
+
+
+# Visual Scripting nodes that reach into arbitrary .NET via reflection. These
+# are the entire "dangerous surface" of Visual Scripting (File.IO, networking,
+# Process.Start, etc. are NOT exposed as dedicated nodes — they're only
+# reachable through these four). Block them outright; MyVillage Custom Units
+# provide the curated alternative.
+FORBIDDEN_GRAPH_NODES = {
+    "Unity.VisualScripting.InvokeMember",
+    "Unity.VisualScripting.GetMember",
+    "Unity.VisualScripting.SetMember",
+    "Unity.VisualScripting.Expose",
+}
+
+
+def _normalize_type(qualname: str) -> str:
+    """Strip assembly suffix from an assembly-qualified .NET type name.
+    'Unity.VisualScripting.InvokeMember, Unity.VisualScripting.Flow'
+    -> 'Unity.VisualScripting.InvokeMember'
+    """
+    if not qualname:
+        return ""
+    return qualname.split(",", 1)[0].strip()
+
+
+def _walk_for_types(obj, types_out):
+    """Recursively walk a parsed JSON object collecting every '$type' value."""
+    if isinstance(obj, dict):
+        t = obj.get("$type")
+        if isinstance(t, str):
+            types_out.append((_normalize_type(t), obj))
+        for v in obj.values():
+            _walk_for_types(v, types_out)
+    elif isinstance(obj, list):
+        for v in obj:
+            _walk_for_types(v, types_out)
+
+
+def _extract_graph_json(obj):
+    """Return the inner FullSerializer JSON string from a ScriptGraphAsset
+    or StateGraphAsset typetree, or None if not present."""
+    try:
+        tree = obj.read_typetree()
+    except Exception:
+        return None
+    # The Macro<TGraph> shape stores the graph at _data._json.
+    data = tree.get("_data") if isinstance(tree, dict) else None
+    if isinstance(data, dict):
+        s = data.get("_json")
+        if isinstance(s, str) and s:
+            return s
+    # Fallback: some asset variants put _json at the root.
+    s = tree.get("_json") if isinstance(tree, dict) else None
+    if isinstance(s, str) and s:
+        return s
+    return None
+
+
+def main():
+    if len(sys.argv) != 3:
+        _error("Usage: preflight.py <bundle_path> <allowlist_json_path>")
+
+    bundle_path = Path(sys.argv[1])
+    allowlist_path = Path(sys.argv[2])
+
+    if not bundle_path.exists():
+        _error(f"Bundle not found: {bundle_path}")
+    if not allowlist_path.exists():
+        _error(f"Allowlist not found: {allowlist_path}")
+
+    try:
+        import UnityPy
+    except ImportError:
+        _error(
+            "UnityPy is not installed in this Python environment. "
+            "Install with: pip install 'UnityPy==1.25.0' "
+            "(or 'pip3 install' on systems where pip points at Python 2)."
+        )
+
+    try:
+        allowlist = json.loads(allowlist_path.read_text())
+    except json.JSONDecodeError as e:
+        _error(f"Allowlist JSON parse error: {e}")
+
+    allowed_assemblies = {entry["name"] for entry in allowlist.get("assemblies", []) if "name" in entry}
+    allowed_nodes = set(allowlist.get("nodes") or [])
+
+    try:
+        env = UnityPy.load(str(bundle_path))
+    except Exception as e:
+        _error(f"Failed to parse bundle (UnityPy): {e}")
+
+    violations = []
+    scripts_seen = 0
+    graphs_seen = 0
+    nodes_seen = 0
+    seen_script_keys = set()
+    seen_node_violations = set()  # dedupe (kind, type) pairs
+
+    # ── MonoScript checks (M1) ────────────────────────────────────────────
+    for obj in env.objects:
+        if obj.type.name != "MonoScript":
+            continue
+        scripts_seen += 1
+        try:
+            tree = obj.read_typetree()
+        except Exception as e:
+            violations.append({
+                "kind": "unreadable_script",
+                "reason": f"Failed to read MonoScript at path_id {obj.path_id}: {e}",
+            })
+            continue
+
+        assembly = tree.get("m_AssemblyName") or ""
+        namespace = tree.get("m_Namespace") or ""
+        class_name = tree.get("m_ClassName") or ""
+        key = (assembly, namespace, class_name)
+
+        if _is_builtin_assembly(assembly):
+            continue
+        if assembly in allowed_assemblies:
+            continue
+        if key in seen_script_keys:
+            continue
+        seen_script_keys.add(key)
+        violations.append({
+            "kind": "unauthorized_script",
+            "assembly": assembly or "<empty>",
+            "namespace": namespace,
+            "className": class_name,
+            "reason": (
+                f"Script references assembly '{assembly}' which is not in the SDK "
+                f"allowlist and is not a Unity built-in. Convert to MissionBase + "
+                f"MissionConfig or a Visual Scripting graph."
+            ),
+        })
+
+    # ── Visual Scripting graph checks (M2) ────────────────────────────────
+    # Skip entirely if the allowlist doesn't declare a `nodes` list yet
+    # (older SDK versions pre-M2 don't need this enforcement).
+    if allowed_nodes:
+        for obj in env.objects:
+            if obj.type.name not in ("ScriptGraphAsset", "StateGraphAsset", "MonoBehaviour"):
+                continue
+            graph_json = _extract_graph_json(obj)
+            if not graph_json:
+                continue
+            graphs_seen += 1
+            try:
+                graph = json.loads(graph_json)
+            except json.JSONDecodeError as e:
+                violations.append({
+                    "kind": "unparseable_graph",
+                    "reason": f"Visual Scripting graph JSON parse failed: {e}",
+                })
+                continue
+
+            collected = []
+            _walk_for_types(graph, collected)
+            nodes_seen += len(collected)
+
+            for type_name, _node in collected:
+                if not type_name:
+                    continue
+                # Block the four reflection nodes outright
+                if type_name in FORBIDDEN_GRAPH_NODES:
+                    dedup_key = ("forbidden_node", type_name)
+                    if dedup_key in seen_node_violations:
+                        continue
+                    seen_node_violations.add(dedup_key)
+                    violations.append({
+                        "kind": "forbidden_node",
+                        "unitType": type_name,
+                        "reason": (
+                            "Visual Scripting reflection nodes (InvokeMember, GetMember, "
+                            "SetMember, Expose) are blocked. Use a MyVillage Custom Unit "
+                            "(under the 'MyVillage' category in the node finder) instead."
+                        ),
+                    })
+                    continue
+                # Only enforce positive allowlist on Unit-shaped entries. The
+                # FullSerializer JSON contains many $type entries that aren't
+                # graph nodes (Vector3 values, color literals, etc.). Limit
+                # the positive check to Unity.VisualScripting.* + MyVillage.*
+                # which are the namespaces graph units live in.
+                if not (type_name.startswith("Unity.VisualScripting.")
+                        or type_name.startswith("MyVillage.GameKit.VisualScripting.")):
+                    continue
+                if type_name in allowed_nodes:
+                    continue
+                dedup_key = ("unauthorized_node", type_name)
+                if dedup_key in seen_node_violations:
+                    continue
+                seen_node_violations.add(dedup_key)
+                violations.append({
+                    "kind": "unauthorized_node",
+                    "unitType": type_name,
+                    "reason": (
+                        f"Visual Scripting node '{type_name}' is not on the GameKit "
+                        f"allowlist for this SDK version. If your game needs this, "
+                        f"contact MyVillage to request the node be added."
+                    ),
+                })
+
+    # ── Embedded DLLs are always forbidden ────────────────────────────────
+    embedded_files = []
+    for cab_name, _cab in getattr(env, "files", {}).items():
+        if isinstance(cab_name, str) and cab_name.lower().endswith(".dll"):
+            embedded_files.append(cab_name)
+    for name in embedded_files:
+        violations.append({
+            "kind": "embedded_dll",
+            "path": name,
+            "reason": "Bundle contains an embedded .dll. Bundles may only ship assets, not compiled assemblies.",
+        })
+
+    result = {
+        "status": "fail" if violations else "pass",
+        "bundle": str(bundle_path),
+        "scriptsSeen": scripts_seen,
+        "graphsSeen": graphs_seen,
+        "nodesSeen": nodes_seen,
+        "allowedAssemblies": sorted(allowed_assemblies),
+        "allowedNodeCount": len(allowed_nodes),
+        "violations": violations,
+        "violationCount": len(violations),
+    }
+    _emit(result, 1 if violations else 0)
+
+
+if __name__ == "__main__":
+    main()

package/tools/preflight/requirements.txt

@@ -0,0 +1 @@
+UnityPy==1.25.0