fix(security): restrict file reference resolution to allowed roots

Prevent arbitrary file reads through  references by resolving targets canonically and rejecting absolute paths, traversal, and symlink escapes outside the prompt directory unless the host explicitly provides additional allowed file roots.

Addresses GHSA-wxhm-2mq7-7697.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: sethjuarez

README.md

@@ -221,7 +221,9 @@ Jinja2 (`{{variable}}`, `{% if %}`, `{% for %}`) or Mustache (`{{variable}}`, `{
 |--------|---------|
 | `${env:VAR}` | Environment variable (required) |
 | `${env:VAR:default}` | With fallback value |
-| `${file:path.json}` | Load file content |
+| `${file:path.json}` | Load file content from the prompt directory tree |
+
+`${file:...}` references are scoped to the containing `.prompty` file's directory by default. Host applications can opt into additional allowed roots through runtime load options; prompts cannot grant themselves broader filesystem access.
 
 ### Legacy format
 

runtime/csharp/Prompty.Anthropic/Prompty.Anthropic.csproj

@@ -4,7 +4,7 @@
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>2.0.0-beta.1</Version>
+    <Version>2.0.0-beta.2</Version>
     <PackageId>Prompty.Anthropic</PackageId>
     <Authors>Microsoft</Authors>
     <Description>Anthropic provider for Prompty — executor and processor for Claude models via the Anthropic Messages API.</Description>

runtime/csharp/Prompty.Core.Tests/LoaderTests.cs

@@ -250,6 +250,104 @@ public void Load_FileRef_ResolvesJsonFile()
         Assert.Equal("shared-key-12345", apiKey.ApiKey);
     }
 
+    [Fact]
+    public void Load_FileRef_TraversalOutsidePromptDir_Throws()
+    {
+        var root = Directory.CreateTempSubdirectory("prompty-loader-");
+        try
+        {
+            var promptDir = Directory.CreateDirectory(Path.Combine(root.FullName, "prompts"));
+            File.WriteAllText(Path.Combine(root.FullName, "secret.txt"), "secret");
+            var prompt = Path.Combine(promptDir.FullName, "bad.prompty");
+            File.WriteAllText(prompt, "---\nname: bad\ndescription: \"${file:../secret.txt}\"\n---\nHello\n");
+
+            var ex = Assert.Throws<InvalidOperationException>(() => PromptyLoader.Load(prompt));
+            Assert.Contains("outside allowed roots", ex.Message);
+        }
+        finally
+        {
+            root.Delete(recursive: true);
+        }
+    }
+
+    [Fact]
+    public void Load_FileRef_AbsolutePathOutsidePromptDir_Throws()
+    {
+        var root = Directory.CreateTempSubdirectory("prompty-loader-");
+        try
+        {
+            var promptDir = Directory.CreateDirectory(Path.Combine(root.FullName, "prompts"));
+            var secret = Path.Combine(root.FullName, "secret.txt");
+            File.WriteAllText(secret, "secret");
+            var prompt = Path.Combine(promptDir.FullName, "bad.prompty");
+            File.WriteAllText(
+                prompt,
+                $"---\nname: bad\ndescription: \"${{file:{secret.Replace("\\", "/")}}}\"\n---\nHello\n");
+
+            var ex = Assert.Throws<InvalidOperationException>(() => PromptyLoader.Load(prompt));
+            Assert.Contains("outside allowed roots", ex.Message);
+        }
+        finally
+        {
+            root.Delete(recursive: true);
+        }
+    }
+
+    [Fact]
+    public void Load_FileRef_AllowedRootPermitsSharedFile()
+    {
+        var root = Directory.CreateTempSubdirectory("prompty-loader-");
+        try
+        {
+            var promptDir = Directory.CreateDirectory(Path.Combine(root.FullName, "prompts"));
+            var sharedDir = Directory.CreateDirectory(Path.Combine(root.FullName, "shared"));
+            File.WriteAllText(Path.Combine(sharedDir.FullName, "description.txt"), "shared description");
+            var prompt = Path.Combine(promptDir.FullName, "shared.prompty");
+            File.WriteAllText(prompt, "---\nname: shared\ndescription: \"${file:../shared/description.txt}\"\n---\nHello\n");
+
+            var agent = PromptyLoader.Load(
+                prompt,
+                new PromptyLoadOptions { AllowedFileRoots = [sharedDir.FullName] });
+
+            Assert.Equal("shared description", agent.Description);
+        }
+        finally
+        {
+            root.Delete(recursive: true);
+        }
+    }
+
+    [Fact]
+    public void Load_FileRef_SymlinkEscape_Throws()
+    {
+        var root = Directory.CreateTempSubdirectory("prompty-loader-");
+        try
+        {
+            var promptDir = Directory.CreateDirectory(Path.Combine(root.FullName, "prompts"));
+            var secret = Path.Combine(root.FullName, "secret.txt");
+            File.WriteAllText(secret, "secret");
+            var link = Path.Combine(promptDir.FullName, "secret-link.txt");
+            try
+            {
+                File.CreateSymbolicLink(link, secret);
+            }
+            catch
+            {
+                return;
+            }
+
+            var prompt = Path.Combine(promptDir.FullName, "bad.prompty");
+            File.WriteAllText(prompt, "---\nname: bad\ndescription: \"${file:secret-link.txt}\"\n---\nHello\n");
+
+            var ex = Assert.Throws<InvalidOperationException>(() => PromptyLoader.Load(prompt));
+            Assert.Contains("outside allowed roots", ex.Message);
+        }
+        finally
+        {
+            root.Delete(recursive: true);
+        }
+    }
+
     // --- Tools ---
 
     [Fact]

runtime/csharp/Prompty.Core.Tests/SpecVectorTests.cs

@@ -254,7 +254,7 @@ public void LoadVectors_AllPass()
 
                     var ctx = new LoadContext
                     {
-                        PreProcess = d => ReferenceResolver.ResolveReferences(d, "."),
+                        PreProcess = d => ReferenceResolver.ResolveReferences(d, ".", [Path.GetFullPath(".")]),
                     };
 
                     var agent = Prompty.Load(data, ctx);

runtime/csharp/Prompty.Core/Prompty.Core.csproj

@@ -4,7 +4,7 @@
     <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>2.0.0-beta.1</Version>
+    <Version>2.0.0-beta.2</Version>
     <PackageId>Prompty.Core</PackageId>
     <Authors>Microsoft</Authors>
     <Description>Prompty is an asset class and format for LLM prompts. Core library with loader, pipeline, renderers, parsers, and tracing.</Description>

runtime/csharp/Prompty.Core/PromptyLoadOptions.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Prompty.Core;
+
+/// <summary>
+/// Options for loading .prompty files.
+/// </summary>
+public sealed class PromptyLoadOptions
+{
+    /// <summary>
+    /// Additional directories that ${file:...} references may read from.
+    /// The prompt file's directory is always allowed.
+    /// </summary>
+    public IEnumerable<string> AllowedFileRoots { get; init; } = [];
+}

runtime/csharp/Prompty.Core/PromptyLoader.cs

@@ -12,17 +12,18 @@ public static class PromptyLoader
     /// Load a .prompty file and return a fully typed Prompty instance.
     /// </summary>
     /// <param name="path">Path to the .prompty file (absolute or relative to cwd).</param>
+    /// <param name="options">Optional load behavior, including additional allowed file roots.</param>
     /// <returns>A loaded Prompty instance with instructions from the markdown body.</returns>
     /// <exception cref="FileNotFoundException">If the file does not exist.</exception>
     /// <exception cref="InvalidOperationException">If frontmatter is invalid or env vars are missing.</exception>
-    public static Prompty Load(string path)
+    public static Prompty Load(string path, PromptyLoadOptions? options = null)
     {
         var fullPath = Path.GetFullPath(path);
         if (!File.Exists(fullPath))
             throw new FileNotFoundException($"Prompty file not found: '{fullPath}'", fullPath);
 
         var contents = File.ReadAllText(fullPath);
-        return Build(contents, fullPath);
+        return Build(contents, fullPath, options);
     }
 
     /// <summary>
@@ -32,27 +33,42 @@ public static Prompty Load(string path)
     /// <param name="cancellationToken">Optional cancellation token.</param>
     /// <returns>A loaded Prompty instance with instructions from the markdown body.</returns>
     public static async Task<Prompty> LoadAsync(string path, CancellationToken cancellationToken = default)
+    {
+        return await LoadAsync(path, options: null, cancellationToken);
+    }
+
+    /// <summary>
+    /// Asynchronously load a .prompty file with explicit load options.
+    /// </summary>
+    /// <param name="path">Path to the .prompty file (absolute or relative to cwd).</param>
+    /// <param name="options">Optional load behavior, including additional allowed file roots.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>A loaded Prompty instance with instructions from the markdown body.</returns>
+    public static async Task<Prompty> LoadAsync(
+        string path,
+        PromptyLoadOptions? options,
+        CancellationToken cancellationToken = default)
     {
         var fullPath = Path.GetFullPath(path);
         if (!File.Exists(fullPath))
             throw new FileNotFoundException($"Prompty file not found: '{fullPath}'", fullPath);
 
         var contents = await File.ReadAllTextAsync(fullPath, cancellationToken);
-        return Build(contents, fullPath);
+        return Build(contents, fullPath, options);
     }
 
     /// <summary>
     /// Core loading logic shared by sync and async paths.
     /// </summary>
-    private static Prompty Build(string contents, string fullPath)
+    private static Prompty Build(string contents, string fullPath, PromptyLoadOptions? options)
     {
         // 1. Split frontmatter + body
         var data = FrontmatterParser.Parse(contents);
 
         // 2. Load via typed model with ${env:}/${file:} resolution
         var ctx = new LoadContext
         {
-            PreProcess = ReferenceResolver.CreatePreProcess(fullPath),
+            PreProcess = ReferenceResolver.CreatePreProcess(fullPath, options?.AllowedFileRoots),
         };
 
         var agent = Prompty.Load(data, ctx);

runtime/csharp/Prompty.Core/ReferenceResolver.cs

@@ -17,21 +17,31 @@ public static class ReferenceResolver
     /// References are resolved relative to the .prompty file's parent directory.
     /// </summary>
     /// <param name="promptyFilePath">Absolute path to the .prompty file (for resolving relative ${file:} refs).</param>
+    /// <param name="allowedFileRoots">Additional directories that ${file:} references may read from.</param>
     /// <returns>A callback suitable for LoadContext.PreProcess.</returns>
-    public static Func<Dictionary<string, object?>, Dictionary<string, object?>> CreatePreProcess(string promptyFilePath)
+    public static Func<Dictionary<string, object?>, Dictionary<string, object?>> CreatePreProcess(
+        string promptyFilePath,
+        IEnumerable<string>? allowedFileRoots = null)
     {
-        var parentDir = Path.GetDirectoryName(Path.GetFullPath(promptyFilePath))
+        var parentDir = Path.GetDirectoryName(GetCanonicalPath(promptyFilePath))
             ?? throw new ArgumentException($"Cannot determine parent directory of '{promptyFilePath}'");
+        var allowedRoots = new[] { parentDir }
+            .Concat(allowedFileRoots ?? [])
+            .Select(GetCanonicalPath)
+            .ToArray();
 
-        return data => ResolveReferences(data, parentDir);
+        return data => ResolveReferences(data, parentDir, allowedRoots);
     }
 
     /// <summary>
     /// Walks a dictionary and resolves any string values matching ${protocol:value} patterns.
     /// Only processes top-level string values in the given dictionary (recursive walking is
     /// handled by LoadContext calling PreProcess on each nested dict).
     /// </summary>
-    internal static Dictionary<string, object?> ResolveReferences(Dictionary<string, object?> data, string parentDir)
+    internal static Dictionary<string, object?> ResolveReferences(
+        Dictionary<string, object?> data,
+        string parentDir,
+        IReadOnlyCollection<string> allowedRoots)
     {
         foreach (var key in data.Keys.ToList())
         {
@@ -55,7 +65,7 @@ public static class ReferenceResolver
                     data[key] = ResolveEnvVar(remainder, key);
                     break;
                 case "file":
-                    data[key] = ResolveFileRef(remainder, parentDir, key);
+                    data[key] = ResolveFileRef(remainder, parentDir, allowedRoots, key);
                     break;
                     // Unknown protocol: leave unchanged per spec §4
             }
@@ -100,13 +110,26 @@ private static object ResolveEnvVar(string remainder, string key)
     /// Resolves ${file:relative/path}. Loads content based on file extension:
     /// .json → parsed as JSON object, .yaml/.yml → parsed as YAML object, else → raw text.
     /// </summary>
-    private static object ResolveFileRef(string relativePath, string parentDir, string key)
+    private static object ResolveFileRef(
+        string relativePath,
+        string parentDir,
+        IReadOnlyCollection<string> allowedRoots,
+        string key)
     {
-        var fullPath = Path.GetFullPath(Path.Combine(parentDir, relativePath));
+        var fullPath = Path.IsPathRooted(relativePath)
+            ? Path.GetFullPath(relativePath)
+            : Path.GetFullPath(Path.Combine(parentDir, relativePath));
         if (!File.Exists(fullPath))
             throw new FileNotFoundException(
                 $"Referenced file '{relativePath}' not found (resolved to '{fullPath}', key: '{key}').");
 
+        fullPath = GetCanonicalPath(fullPath);
+        if (!allowedRoots.Any(root => IsWithinRoot(fullPath, root)))
+        {
+            throw new InvalidOperationException(
+                $"File reference '{relativePath}' resolves outside allowed roots (resolved to '{fullPath}', key: '{key}').");
+        }
+
         var content = File.ReadAllText(fullPath);
         var ext = Path.GetExtension(fullPath).ToLowerInvariant();
 
@@ -136,4 +159,30 @@ private static object LoadYamlAsDict(string content)
         var result = YamlUtils.Deserializer.Deserialize<Dictionary<string, object?>>(content);
         return result ?? new Dictionary<string, object?>();
     }
+
+    private static bool IsWithinRoot(string path, string root)
+    {
+        var relative = Path.GetRelativePath(root, path);
+        return relative == "."
+            || (!relative.StartsWith("..", StringComparison.Ordinal)
+                && !Path.IsPathRooted(relative));
+    }
+
+    private static string GetCanonicalPath(string path)
+    {
+        var fullPath = Path.GetFullPath(path);
+        if (File.Exists(fullPath))
+        {
+            var file = new FileInfo(fullPath);
+            var target = file.ResolveLinkTarget(returnFinalTarget: true);
+            return Path.GetFullPath(target?.FullName ?? file.FullName);
+        }
+        if (Directory.Exists(fullPath))
+        {
+            var directory = new DirectoryInfo(fullPath);
+            var target = directory.ResolveLinkTarget(returnFinalTarget: true);
+            return Path.GetFullPath(target?.FullName ?? directory.FullName);
+        }
+        return fullPath;
+    }
 }

runtime/csharp/Prompty.Foundry/Prompty.Foundry.csproj

@@ -6,7 +6,7 @@
     <Nullable>enable</Nullable>
     <NoWarn>OPENAI001;CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <Version>2.0.0-beta.1</Version>
+    <Version>2.0.0-beta.2</Version>
     <PackageId>Prompty.Foundry</PackageId>
     <Authors>Microsoft</Authors>
     <Description>Microsoft Foundry (Azure OpenAI) provider for Prompty — executor and processor for Azure-hosted models.</Description>

runtime/csharp/Prompty.OpenAI/Prompty.OpenAI.csproj

@@ -6,7 +6,7 @@
     <Nullable>enable</Nullable>
     <NoWarn>OPENAI001;CS1591</NoWarn>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <Version>2.0.0-beta.1</Version>
+    <Version>2.0.0-beta.2</Version>
     <PackageId>Prompty.OpenAI</PackageId>
     <Authors>Microsoft</Authors>
     <Description>OpenAI provider for Prompty — executor and processor for OpenAI chat, embedding, image, and agent APIs.</Description>