ScadaBridge/docs/plans/2026-09-28-script-file-access-design.md

Script file access — the Files global (2026-09-28)

Problem

A Delmia recipe download hands the machine a DownloadPath; in production the Galaxy DelmiaReceiver object's own script opens that text file, parses it and loads the values into its tags. ScadaBridge scripts cannot do the same thing: the trust policy forbids System.IO outright, and the deploy gate refuses any script that names a System.IO type. So an in-memory test machine (and any future ScadaBridge-side receiver) could exercise the handshake but never the file parse.

Options considered

1. Leave parsing in the Galaxy. No change; test machines never parse.
2. A small file-reader HTTP service reached through ExternalSystem.Call. No trust-model change, but a new service to deploy and secure on every site.
3. A host-mediated, allow-listed platform API. Chosen (user decision). A deliberate, narrow exception to the trust boundary: the script never touches System.IO; the host reads on its behalf, only beneath directories an administrator lists.

Rejected outright: reading through SQL Server (OPENROWSET(BULK …) via Database.Connection) — needs elevated SQL rights, reads the SQL host's filesystem, and sidesteps the trust policy.

Decisions

• Surface. Files.ReadTextAsync(path), Files.ReadLinesAsync(path), Files.ExistsAsync(path) on the site ScriptGlobals (+ Instance.Files), each taking an optional CancellationToken. Read-only — no write, list, delete or directory enumeration; add one only with its own use case.
• Off by default. ScadaBridge:SiteRuntime:ScriptFileAccess:AllowedRoots (absolute local/UNC dirs, default empty) and MaxFileBytes (default 1 MiB, 1…64 MiB). No roots ⇒ every call throws Disabled, so upgrading a site changes nothing until an operator opts in. Validated at boot.
• Guard (host side, ScriptFileReader). Fully-qualified path; no device paths or alternate data streams; canonicalize, then a directory-boundary prefix match against each root; no reparse point on the file or any directory between root and file; size cap enforced before and during the read.
• One exception type in Commons — ScriptFileAccessException + ScriptFileAccessFailure — because scripts cannot name System.IO exceptions. Commons.Types.Scripts joins the default script imports on every surface so it binds by short name.
• Site scripts only. Inbound API scripts run on central and have no Files. The Test Run sandbox mirrors the member (so scripts bind) and throws Disabled at run time. ScriptCompileSurface.CompileFiles mirrors it for the deploy gate; parity is pinned by CompileSurfaceParityTests.
• Not audited. File reads are not one of the audit channels; refusals log a node Warning.

Accepted residuals

• Time-of-check/time-of-use between the link check and the open: a writer inside an allowed root could swap a file for a link in between. Bounded by the allow-list (only administrator-chosen directories) and by the API being read-only.
• The node's service account permissions still apply; on a site pair both nodes need the same roots and the same access (a script can run on either node after failover).

First consumer

docker/seed-mes-test-machine.sh: the SimDelmiaRecipe simulator on TestMesMachine reads the downloaded recipe file (RecipeValueName,RecipeValue per line), types each value (int → double → bool → string) and loads it into the matching TestDelmiaReceiver recipe attributes, rejecting unknown names and malformed lines. Sample files: docker/recipes/.