Decode.Storage.FileSystem 2.0.0

Decode.Storage.FileSystem

Local FileSystem storage implementation of IStorageService for the Decode.Storage ecosystem.

📦 Installation

dotnet add package Decode.Storage.FileSystem

🛠️ Usage

1. Register Services

In your Program.cs or Startup.cs:

using Decode.Storage.FileSystem.Extensions;

builder.Services.AddFileSystemStorage(options =>
{
    options.BasePath = "C:\\StorageRoot"; // Or load from configuration
});

2. Inject and Use in Services

using Decode.Storage.Abstractions;

public class DocumentService
{
    private readonly IStorageService _storage;

    public DocumentService(IStorageService storage)
    {
        _storage = storage;
    }

    public async Task SaveReportAsync(string fileName, Stream content)
    {
        // Writes to a temporary file first, then moves it into place with overwrite in a single
        // operation, so readers never observe a partially written or momentarily missing file.
        string savedPath = await _storage.UploadAsync($"reports/{fileName}", content, "application/pdf");
    }

    public async Task<StorageFile?> GetReportAsync(string fileName)
    {
        // Safe streaming and reading
        return await _storage.DownloadAsync($"reports/{fileName}");
    }
}

🔒 Path Containment (changed in 2.0.0)

Every path is resolved against BasePath and verified to stay inside it. Paths that are rooted, or that resolve outside the base directory, are rejected with ArgumentException:

await _storage.UploadAsync("reports/2026/q1.pdf", content); // ok
await _storage.UploadAsync("../../etc/passwd", content);    // ArgumentException
await _storage.UploadAsync(@"C:\Windows\System32\x.dll", content); // ArgumentException

Versions before 2.0.0 sanitized by stripping ".." substrings and then called Path.Combine(basePath, cleanPath). Path.Combine discards its first argument when the second is rooted, so any absolute path escaped the storage root entirely — arbitrary read, write and delete across the filesystem. The substring stripping was also lossy: a legitimate name like report..v2.pdf was silently rewritten to reportv2.pdf.

Both are fixed: containment is now proven by canonicalizing the resolved path, and file names are never rewritten.

Note on GetUrlAsync. It returns a file:// URI containing the absolute server path. That leaks your directory layout if handed to a client — treat it as internal-only.

📄 License

MIT License.