feat(scripts): read-only, allow-listed Files global for site scripts; Delmia test receiver parses recipe files

Script file access (design docs/plans/2026-09-28-script-file-access-design.md): Files.ReadTextAsync / ReadLinesAsync / ExistsAsync on site ScriptGlobals (+ Instance.Files), backed by the site-singleton ScriptFileReader. The one host-mediated exception to the System.IO ban - scripts still never name a System.IO type. OFF by default: ScadaBridge:SiteRuntime:ScriptFileAccess:AllowedRoots (empty = every call throws Disabled) + MaxFileBytes (1 MiB, validated 1..64 MiB, roots must be absolute). Guard: fully qualified, no device paths / ADS, canonical path strictly inside a root (directory-boundary match), no reparse point on the file or any directory below the root, size cap before and during the read. Errors are one Commons type, ScriptFileAccessException(+ScriptFileAccessFailure); Commons.Types.Scripts joins the default script imports on every surface so it binds by short name. Mirrored on ScriptCompileSurface (CompileFiles, parity-pinned) and the Test Run sandbox (binds, refuses Disabled). Inbound (central) scripts do not get it. Rig: docker/recipes (sample RecipeValueName,RecipeValue files incl. an invalid one) bind-mounted read-only at /app/recipes on both site-a nodes with AllowedRoots [/app/recipes]. The TestMesMachine SimDelmiaRecipe simulator now reads + parses the downloaded file, converts each value to its recipe tag's type and loads it all-or-nothing (14 new TestDelmiaReceiver attributes); verify-mes-test-machine.sh group A covers accept / re-download / invalid lines / NotFound / OutsideAllowedRoots, VERIFY_GROUPS selects groups (rig: AD).
2026-09-28 10:36:42 -04:00
parent 0af0672597
commit b3021e7c5f
31 changed files with 1157 additions and 77 deletions
@@ -0,0 +1,50 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;
+
+/// <summary>
+/// Why a script's <c>Files.*</c> call was refused or failed (design 2026-09-28).
+/// </summary>
+public enum ScriptFileAccessFailure
+{
+    /// <summary>No allowed roots are configured on this node (the default), or the surface has no file access at all (Test Run sandbox).</summary>
+    Disabled,
+
+    /// <summary>The path is empty, relative, a device/alternate-stream path, or otherwise malformed.</summary>
+    InvalidPath,
+
+    /// <summary>The canonical path is not under any configured allowed root.</summary>
+    OutsideAllowedRoots,
+
+    /// <summary>The file, or a directory between the allowed root and the file, is a symbolic link / junction / reparse point.</summary>
+    LinkNotAllowed,
+
+    /// <summary>The file does not exist (or the path names a directory).</summary>
+    NotFound,
+
+    /// <summary>The file is larger than the configured size cap.</summary>
+    TooLarge,
+
+    /// <summary>The operating system refused or failed the read (permissions, sharing violation, I/O error).</summary>
+    IoError,
+}
+
+/// <summary>
+/// The single exception type a script's <c>Files.*</c> calls throw. Scripts cannot name
+/// <c>System.IO</c> exception types (the trust policy forbids the namespace), so every refusal
+/// and every I/O failure is surfaced as this Commons type, which a script can catch by name and
+/// branch on via <see cref="Failure"/>.
+/// </summary>
+public sealed class ScriptFileAccessException : Exception
+{
+    /// <summary>Initializes a new instance.</summary>
+    /// <param name="failure">The failure category.</param>
+    /// <param name="message">A message naming the path and the reason.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public ScriptFileAccessException(ScriptFileAccessFailure failure, string message, Exception? innerException = null)
+        : base(message, innerException)
+    {
+        Failure = failure;
+    }
+
+    /// <summary>Why the call was refused or failed.</summary>
+    public ScriptFileAccessFailure Failure { get; }
+}