GM.FileStorage.Encryption 2.0.3

There is a newer version of this package available.
See the version list below for details.
dotnet add package GM.FileStorage.Encryption --version 2.0.3
                    
NuGet\Install-Package GM.FileStorage.Encryption -Version 2.0.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GM.FileStorage.Encryption" Version="2.0.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="GM.FileStorage.Encryption" Version="2.0.3" />
                    
Directory.Packages.props
<PackageReference Include="GM.FileStorage.Encryption" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add GM.FileStorage.Encryption --version 2.0.3
                    
#r "nuget: GM.FileStorage.Encryption, 2.0.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package GM.FileStorage.Encryption@2.0.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=GM.FileStorage.Encryption&version=2.0.3
                    
Install as a Cake Addin
#tool nuget:?package=GM.FileStorage.Encryption&version=2.0.3
                    
Install as a Cake Tool

<p align="center"> <img src="https://raw.githubusercontent.com/gmetskhvarishvili/GM.FileStorage/master/icon.png" alt="GM.FileStorage" width="140" height="140" /> </p>

GM.FileStorage

CI NuGet License: MIT

A provider-agnostic file/blob storage abstraction for .NET. Depend on one interface — IFileStorageService — with streaming upload/download (no loading large files into memory), metadata + SHA-256 checksum validation, presigned URLs, and a pluggable key/path strategy (e.g. tenant/user-scoped folders). The backend is chosen by configuration, so switching disk → S3 → Azure Blob is a config change, not a code change. Targets .NET 10.

Packages

Core has no provider dependencies; each backend is its own package (like GM.Messaging / its transports). They version and release in lockstep:

Package Backend Status
GM.FileStorage core abstraction + config-driven selection ✅ shipped
GM.FileStorage.Local local disk (dev / tests) ✅ shipped
GM.FileStorage.S3 AWS S3 / S3-compatible (MinIO) ✅ shipped
GM.FileStorage.AzureBlob Azure Blob Storage ✅ shipped
GM.FileStorage.Encryption encryption at rest for any provider (AES-256-GCM, a key per file) 🆕 new
GM.FileStorage.Domain domain model for keeping files in your database: GMStoredFile + metadata 🆕 new
GM.FileStorage.Persistence EF Core configurations + table names for those entities 🆕 new
dotnet add package GM.FileStorage
dotnet add package GM.FileStorage.Local

The interface

public interface IFileStorageService
{
    Task<FileMetadata>       UploadAsync(FileUploadRequest request, CancellationToken ct = default);
    Task<FileDownloadResult> DownloadAsync(string key, CancellationToken ct = default);
    Task<FileDownloadResult> DownloadAsync(string key, FileByteRange range, CancellationToken ct = default);
    Task<bool>               ExistsAsync(string key, CancellationToken ct = default);
    Task                     DeleteAsync(string key, CancellationToken ct = default);
    Task<Uri>                GetPresignedUrlAsync(string key, PresignedUrlRequest request, CancellationToken ct = default);
}

No provider types leak into the surface — just streams, keys and the GM types:

  • FileUploadRequest — Stream Content, FileName, ContentType, optional Key, Visibility (Private/Public), custom Metadata, and an optional ExpectedChecksum.
  • FileMetadata — Key, FileName, ContentType, Size, Checksum, Visibility, LastModifiedUtc, Metadata.
  • FileDownloadResult — a disposable Stream Content + FileMetadata (streamed, not buffered).
  • PresignedUrlRequest — Expiry + Operation (Read/Write).
  • IFileKeyStrategy — decides the storage key when a request doesn't set one.

Quick start

using GM.FileStorage;
using GM.FileStorage.Local;

builder.Services.AddGMFileStorage(builder.Configuration);   // reads FileStorage:Provider
builder.Services.AddGMLocalFileStorage(builder.Configuration); // contributes the "Local" backend
// appsettings.json
"FileStorage": {
  "Provider": "Local",                 // swap to "S3" / "AzureBlob" once those packages are added
  "Local": { "RootPath": "App_Data/files", "PublicBaseUrl": "http://localhost:5000/files" }
}

Then inject IFileStorageService — the same code works on any backend:

public class KycDocuments(IFileStorageService storage)
{
    public async Task<string> StoreAsync(Stream file, string fileName, string tenantId, string userId)
    {
        var meta = await storage.UploadAsync(new FileUploadRequest(file, fileName, "application/pdf")
        {
            Visibility = FileVisibility.Private,
            Metadata = new Dictionary<string, string> { ["tenantId"] = tenantId, ["userId"] = userId },
            // ExpectedChecksum = "<sha256>",  // reject if the bytes don't match end to end
        });
        return meta.Key;   // e.g. tenants/acme/users/u1/9f1c…a3.pdf with a tenant/user key strategy
    }

    public async Task<Uri> LinkAsync(string key) =>
        await storage.GetPresignedUrlAsync(key, new PresignedUrlRequest { Expiry = TimeSpan.FromMinutes(10) });
}

Config-driven provider selection

AddGMFileStorage resolves IFileStorageService to the backend named by FileStorage:Provider. Each provider package registers itself as a keyed service under its name ("Local", "S3", "AzureBlob"). Reference the providers you might use, call their AddGM… methods, and pick between them purely in config — no code change to swap.

Key layout: a template, or your own strategy

Without configuration, keys are date-partitioned and collision-free (2026/08/02/{guid}.pdf). To lay them out differently, set a key template. No code is needed:

"FileStorage": {
  "KeyTemplate": "{category}/{shard}/{id}{ext}"   // → documents/9f/9f1c…a3.pdf, images/4e/4e07…png
}
Token Becomes
{id} a random 32-hex id; required, so keys never collide
{ext} the file's extension, lower-case and cleaned (.pdf), or nothing
{category} documents, images, videos, audio, archives or other, from the content type
{shard} the id's first two characters: 256 folders, so none grows huge
{date:format} the upload time (UTC), e.g. {date:yyyy/MM}
{meta:name} an upload metadata value, e.g. {meta:tenantId} (_ when absent)
  • Categories come from the verified type. The key strategy gets the content type after the upload rules have run (FileKeyContext.ContentType). With VerifyContentType on, a renamed executable can't land in images/, and an application/octet-stream upload is placed by its detected type.
  • Upload values are cleaned. Metadata values and extensions are reduced to letters, digits, -, _ and ., with no .. and no leading dot, so they can't add folders, climb out of the storage root or break a URL.
  • The template is checked at startup. An unknown token, a missing {id}, unbalanced braces, or an absolute or .. path fails at startup, not at the first upload. FileKeyTemplate.Parse(...) and FileCategories.Of(...) are public if you want them in your own code.

For anything a template can't express, implement IFileKeyStrategy:

public sealed class TenantKeyStrategy : IFileKeyStrategy
{
    public string GenerateKey(FileKeyContext ctx) =>
        $"tenants/{ctx.Metadata["tenantId"]}/{FileCategories.Of(ctx.ContentType)}/{Guid.NewGuid():N}{Path.GetExtension(ctx.FileName)}";
}

builder.Services.AddSingleton<IFileKeyStrategy, TenantKeyStrategy>();

Streaming & integrity

Uploads and downloads stream through an 80 KiB buffer, so a large KYC scan or image is never fully in memory. Every upload's SHA-256 is computed in the same pass; set FileUploadRequest.ExpectedChecksum and a mismatch is rejected with ChecksumMismatchException and nothing is stored.

Upload rules: size, allowed types, real content

Set them once in FileStorage and they apply to every provider. All three are off by default.

"FileStorage": {
  "MaxFileSize": 10485760,                                   // bytes (10 MB); larger → FileTooLargeException
  "AllowedContentTypes": [ "application/pdf", "image/*" ],   // anything else → FileContentTypeNotAllowedException
  "VerifyContentType": true                                  // check the bytes, not just the claimed type
}
  • VerifyContentType reads the upload's first bytes and checks them against the declared type with FileTypeDetector. It knows PDF, the common image, audio and video formats (including HEIC and MOV), ZIP-based Office documents, legacy Office, archives and executables.
    • Mismatch: an .exe declared as image/png throws FileContentTypeMismatchException.
    • Generic type: an upload declared as application/octet-stream takes the detected type.
    • No signature: text formats (plain text, CSV, JSON, SVG) can't be verified and pass as declared.
  • Nothing is kept from a rejected upload.
    • The type check runs before the provider reads anything.
    • An oversize stream fails as the provider reads it: S3 and Azure spool before sending, and the Local provider deletes its partial file.
    • Request bodies that can't seek are handled: the sniffed header is replayed.
  • Detection on its own: FileTypeDetector.Detect(bytes) and FileTypeDetector.Matches(type, bytes) are public.

Ranged downloads (seek in video, resume downloads)

await using var part = await storage.DownloadAsync(key, new FileByteRange(offset: 1_000_000, length: 65_536));
// part.Content: just those bytes · part.Range: the slice served (clamped to the file)
// part.Metadata.Size: the whole file's size · part.Range.Value.ToContentRange(size): "bytes 1000000-1065535/5242880"
  • Built-in providers fetch only the requested bytes: S3 ByteRange, Azure HttpRange, and a seek on Local.
  • Other IFileStorageService implementations get a default that reads from the start and skips ahead.
  • Out-of-range starts: a range starting at or past the end throws FileRangeNotSatisfiableException, which carries the file's Size for an HTTP 416 Content-Range: bytes */size.

Keeping files in your database (GM.FileStorage.Domain + GM.FileStorage.Persistence)

Object storage only answers "give me the file at this key". It can't list "every file for tenant acme", and provider metadata (x-amz-meta-*, blob metadata, the local .gmmeta sidecar) isn't searchable. To do that, keep each file's properties in your own database. The two packages give you the domain model and its EF Core mapping, laid out like GM.Identity; your app subclasses them, as GM.Identity.Samples does.

GM.FileStorage.Domain/
  FileStorage/                                   # bounded context
    StoredFileAggregate/
      Entities/GMStoredFile.cs                   # GMStoredFile<TStoredFile, TStoredFileMetadata>
      Events/GMStoredFile{Uploaded,Deleted,Restored,Activated,Deactivated,Hidden,Unhidden}DomainEvent.cs
    StoredFileMetadataAggregate/
      Entities/GMStoredFileMetadata.cs           # one name/value pair per row
GM.FileStorage.Persistence/
  Configuration/GMStoredFileConfiguration.cs     # generic; override Schema / Table / Configure
  Configuration/GMStoredFileMetadataConfiguration.cs
  GMFileStorageTableNames.cs                     # gm_file_storage.gm_stored_files / gm_stored_file_metadata
  • GMStoredFile (SoftDeletableEntity<Guid> from GM.EntityFramework) holds the key (unique, up to 450 characters), file name, content type, size, checksum, IsPublic and upload time.
    • A file's content never changes after it's created: new content is a new file.
    • StorageKey is where the bytes live. It defaults to Key; pass your own (e.g. a path from the key template, documents/9f/9f1c….pdf) to keep the stored layout separate from the key callers use.
    • A constructor takes the id too. Pass id.ToString() as the key to give callers a single GUID per file, while the bytes sit under a readable folder path.
    • It raises a domain event for each change. On a GenericDbContext, they're written to the domain-event log in the same save.
  • GMStoredFileMetadata holds one metadata pair per row (tenantId = acme), unique per file and name and indexed on (name, value). Filtering files by tenant or user is an index lookup through GMStoredFile.Metadata.
  • Constructors are protected. Your app's aggregates subclass the bases and expose the factories.

In your app's Domain:

public class StoredFile : GMStoredFile<StoredFile, StoredFileMetadata>, IAggregateRoot
{
    private StoredFile() { } // EF Core materialization

    private StoredFile(string key, string fileName, string contentType, long size, string? checksum, bool isPublic, DateTime uploadedAtUtc)
        : base(key, fileName, contentType, size, checksum, isPublic, uploadedAtUtc) { }

    public static StoredFile Create(string key, string fileName, string contentType, long size, string? checksum, bool isPublic, DateTime uploadedAtUtc) =>
        new(key, fileName, contentType, size, checksum, isPublic, uploadedAtUtc);
}
// StoredFileMetadata : GMStoredFileMetadata<StoredFile, StoredFileMetadata>, IAggregateRoot — the same way.

In your app's Persistence:

public class StoredFileConfiguration : GMStoredFileConfiguration<StoredFile, StoredFileMetadata>
{
    protected override string Schema => "file_storage";   // optional: map without the gm_ prefix
}
public class StoredFileMetadataConfiguration : GMStoredFileMetadataConfiguration<StoredFile, StoredFileMetadata>;

Then write an upload command that calls IFileStorageService.UploadAsync. It records StoredFile.Create(...) plus one StoredFileMetadata.Create(...) per pair through your repositories and unit of work. A delete command deletes the bytes and calls SoftRemove(). A list query filters StoredFile with a specification on Metadata. GM.FileStorage.Samples does exactly this.

Encryption at rest (GM.FileStorage.Encryption)

Every file is encrypted before it reaches the provider, so local disk, S3 and Azure only ever hold ciphertext. Your code doesn't change:

  • UploadAsync and DownloadAsync take and return plaintext.
  • Sizes and checksums are the plaintext's.
  • Ranged downloads still work.
builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMS3FileStorage(builder.Configuration);
builder.Services.AddGMFileStorageEncryption(builder.Configuration);   // FileStorage:Encryption
// From secrets (GM.Secrets: appsecrets.json, SECRETS_PROVIDER, environment), never a committed file.
"FileStorage": {
  "Encryption": {
    "ActiveKeyId": "2026-11",
    "Keys": {
      "2026-11": "<base64 of 32 random bytes>",   // wraps new uploads
      "2025-06": "<retired key>"                  // still needed to read files it wrapped
    }
  }
}

Generate a key with openssl rand -base64 32, or Convert.ToBase64String(RandomNumberGenerator.GetBytes(32)).

How a file is protected (envelope encryption)

  • A key per file. Each upload gets a random 256-bit key, and its content is encrypted with AES-256-GCM in 64 KiB chunks. Only one chunk is ever held in memory.
  • The master key wraps the file key. The file key is stored, encrypted by the master key (AES-256-GCM), in a small header at the start of the object, together with the master key's id. The object is therefore self-contained and needs no database.
  • Tampering is detected. Every chunk is authenticated, and its nonce includes the chunk's index and a last-chunk flag (the STREAM construction). An altered, reordered or truncated file throws FileDecryptionException instead of returning garbage.
  • Ranges stay cheap. A ranged download reads the header, then only the chunks that cover the range.

Operating it

  • Rotating the master key: add a new key, make it ActiveKeyId, and keep the old one in Keys. New uploads use the new key and old files keep decrypting. Remove an old key only once no file uses it.
  • Switching encryption on for existing data: files stored before then (with no encryption marker) are served as stored. New uploads are encrypted.
  • Switching it off explicitly: set FileStorage:Encryption:Enabled to false. For example, keep false in a committed appsettings.json and set true together with the keys in secrets. It's on by default, so registering encryption without keys fails as soon as storage is first used, instead of silently storing plaintext.
  • Presigned URLs throw NotSupportedException: a read link would hand out ciphertext, and a write link would bypass encryption. Stream files through your API instead.
  • Upload rules (MaxFileSize, VerifyContentType, …) see the plaintext, because encryption sits closest to the provider.
  • Other key stores: to keep master keys in a KMS or HSM, implement IFileEncryptionKeyProvider.
  • Keyed providers resolved directly bypass encryption, like the upload rules. Always go through IFileStorageService.

Do you need GM.DistributedLock here? (flagged, not assumed)

Core deliberately does not depend on GM.DistributedLock. For the common operations it isn't needed: object stores are last-write-wins per key, and unique keys (the default strategy) mean concurrent uploads don't collide.

A lock is worth it for one specific case: serializing writes to the same logical key — e.g. "only one upload for kyc/{userId}/passport may be in flight," or a read-modify-write on a file. That's an application-level concern, so rather than bake it into every consumer, wrap the upload:

await using var handle = await locks.AcquireAsync($"file:{key}", TimeSpan.FromSeconds(30),
    wait: TimeSpan.FromSeconds(5), retryInterval: TimeSpan.FromMilliseconds(100));
await storage.UploadAsync(request with { Key = key });

If this pattern turns out to be pervasive, a thin optional GM.FileStorage.DistributedLock decorator (IFileStorageService → lock-per-key → inner service) could add it without touching core or any provider. Recommendation: keep it out of core; add the decorator only if the need is real.

S3 and Azure providers

Both map the same IFileStorageService onto their SDK and register a keyed backend, so an app moves from Local → S3 → AzureBlob by configuration alone — no code change.

S3 / MinIO (GM.FileStorage.S3)

builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMS3FileStorage(builder.Configuration);   // FileStorage:S3
"FileStorage": {
  "Provider": "S3",
  "S3": {
    "BucketName": "kyc-docs",
    "Region": "eu-central-1",
    // MinIO / S3-compatible instead of AWS:
    "ServiceUrl": "http://localhost:9000", "ForcePathStyle": true,
    "AccessKey": "…", "SecretKey": "…"      // omit to use the default AWS credential chain
  }
}

PutObject/GetObject streaming, GetPreSignedURL for presigned read/write, object metadata (x-amz-meta-gm-* for filename/checksum/visibility), and CannedACL for Public/Private.

  • Presigned links use the endpoint's scheme, so a plain-HTTP ServiceUrl (MinIO in dev) gets http:// links.

  • Checksums are validated on whole downloads only. The client AddGMS3FileStorage builds sets ResponseChecksumValidation = WHEN_REQUIRED, and whole-object downloads ask for validation. Ranged downloads don't, because some S3-compatible services send the whole object's checksum with a slice, which never matches.

  • If you construct S3FileStorageService with your own IAmazonS3, give it the same setting; otherwise the SDK default (WHEN_SUPPORTED) can fail ranged downloads from such services:

    new AmazonS3Client(credentials, new AmazonS3Config
    {
        ServiceURL = "…",
        ResponseChecksumValidation = ResponseChecksumValidation.WHEN_REQUIRED,
    });
    

Azure Blob (GM.FileStorage.AzureBlob)

builder.Services.AddGMFileStorage(builder.Configuration);
builder.Services.AddGMAzureBlobFileStorage(builder.Configuration);   // FileStorage:AzureBlob
"FileStorage": {
  "Provider": "AzureBlob",
  "AzureBlob": { "ConnectionString": "…", "ContainerName": "kyc" }
}

Block-blob streaming, SAS URLs via GenerateSasUri, and blob metadata. Note: Azure public access is container-scoped, so per-blob Visibility is advisory — use the SAS URL for time-limited access.

Repository layout

GM.FileStorage/            # IFileStorageService, requests/results, key strategy, options, DI selector
GM.FileStorage.Local/      # disk provider (streaming + SHA-256 + sidecar metadata)
GM.FileStorage.S3/         # AWS S3 / MinIO provider
GM.FileStorage.AzureBlob/  # Azure Blob Storage provider
GM.FileStorage.Encryption/ # encryption at rest: per-file AES-256-GCM keys wrapped by master keys
GM.FileStorage.Domain/      # stored-file domain: FileStorage bounded context, GMStoredFile + GMStoredFileMetadata
GM.FileStorage.Persistence/ # EF Core configurations + table names for the stored-file domain
tests/GM.FileStorage.Tests/  # xUnit tests

Building & testing

dotnet build -c Release
dotnet test  -c Release

Releasing

Versioning is automated from Conventional Commits — see CONTRIBUTING.md. All packages share one version (Directory.Build.props) and publish together to nuget.org on each release.

License

MIT — see LICENSE.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
6.0.0 142 11/9/2026
5.0.0 112 11/9/2026
4.4.0 123 11/8/2026
4.3.0 103 11/8/2026
4.2.0 99 11/8/2026
4.1.0 118 11/8/2026
4.0.0 129 11/8/2026
3.3.0 200 11/5/2026
3.2.0 111 11/4/2026
3.1.0 103 11/4/2026
3.0.0 121 11/4/2026
2.0.3 87 11/4/2026
2.0.2 95 11/3/2026
2.0.1 88 11/3/2026
2.0.0 109 11/3/2026