SmooAI.File 2.2.4

SmooAI.File

Magic-byte MIME detection, typed validation errors, and stream helpers for .NET — because Content-Type headers lie.

.NET port of @smooai/file. Built on Mime-Detective for real MIME sniffing (not extension guessing). Wire-compatible semantics with the TypeScript, Python, Go, and Rust ports.

Install

dotnet add package SmooAI.File

Need S3 upload/download helpers? Add the companion package:

dotnet add package SmooAI.File.S3

Split on purpose — apps that only need MIME detection and validation don't pull in AWSSDK.S3.

Quick start

using SmooAI.File;

// From an ASP.NET Core upload
await using var upload = formFile.OpenReadStream();
var file = await SmooFile.CreateFromStreamAsync(upload, options =>
{
    options.Name             = formFile.FileName;
    options.ExpectedMimeType = formFile.ContentType;   // client-claimed
    options.MaxSizeBytes     = 10_000_000;
    options.AllowedMimeTypes = new[] { "image/png", "image/jpeg", "application/pdf" };
});

// One call — throws typed exceptions on violation
file.Validate();

// Detected MIME reflects what the bytes *actually* are
Console.WriteLine(file.Detected.MimeType);   // e.g. "image/png"

// Emit as base64 for an email attachment / data URL
var b64 = await file.ToBase64Async();

// Or persist
await file.SaveToFileAsync("/tmp/upload.bin");

Why magic-byte detection

File extensions and Content-Type headers are untrusted client input. file.docx may actually be a ZIP. A .php can masquerade as image/png. SmooFile.Detected.MimeType reflects the real bytes — and Validate(expectedMimeType: …) throws FileContentMismatchException the moment claim disagrees with content.

// Client uploads a PHP shell renamed to avatar.png
var file = await SmooFile.CreateFromStreamAsync(stream, opts =>
{
    opts.Name             = "avatar.png";
    opts.ExpectedMimeType = "image/png";
});

file.Validate(allowedMimes: new[] { "image/png", "image/jpeg" });
// -> throws FileContentMismatchException
//    Detected: "text/x-php", Expected: "image/png"

Validation errors

One base class — one catch block on the controller. All typed, all actionable, all 400-worthy:

try
{
    file.Validate();
}
catch (FileValidationException ex)
{
    return Results.Problem(ex.Message, statusCode: 400);
}

Creating from other sources

// From a byte buffer
var file = await SmooFile.CreateFromBytesAsync(bytes, opts => { opts.Name = "thing.bin"; });

// From a file path
var file = await SmooFile.CreateFromPathAsync("/tmp/upload.bin");

// From a URL (streams, doesn't buffer the full body into memory)
var file = await SmooFile.CreateFromUrlAsync("https://example.com/report.pdf");

Related

• SmooAI.File.S3 — presigned uploads + S3 helpers (split package)
• @smooai/file — TypeScript / Node
• smooai-file — Rust
• smooai-file — Python
• github.com/SmooAI/file/go/file — Go

License

MIT — © SmooAI