Treats declared MIME types and extensions as hints only, verifies content with sniffing or inspection, and quarantines unknown or mismatched uploads before they enter serving paths.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Upload metadata supplied by clients is untrusted evidence about file content. The system sniffs or inspects initial bytes and applies policy to derive a canonical type before serving. Declared MIME labels and filename extensions may inform UX but never alone authorize download. Unknown content, disallowed types, and dangerous mismatches such as executables masquerading as documents land in quarantine. Only verified-match or explicitly normalized benign differences may pass the serving gate. This block complements virus scanning; MIME verification answers what the bytes claim to be, not whether they are malicious.
Scope
- Post-upload content sniffing, canonical type assignment, and verdict states.
- Quarantine prefixes for unknown, mismatched, and disallowed types.
- Download and signed-URL gating until verification completes.
- Alerts for executable masquerade and blocklist hits.
Outside this block
- Malware scanning verdicts and engine isolation.
- Retention schedules and legal hold.
- Image transcoding or document parsing pipelines.
Contract
- Declared Content-Type and file extension are never sufficient proof for serving; sniff or inspection must run within profile byte limits.
- Serving paths open only for verified-match or type-normalized verdicts defined in the profile; all other verdicts remain non-downloadable.
- Executable or script signatures detected in content receive executable-masquerade-quarantine regardless of declared MIME type or filename extension; benign-looking extensions do not override the quarantine.
- Unknown sniff results quarantine the object and expose verification-pending or blocked status to owners without leaking internal paths.
- Downloads requested before verification completes return verification-pending and do not issue serving URLs.
- Canonical type stored on the object record reflects sniff plus policy, with declared values retained only as audit metadata.
Implementation guidance
- Run verification immediately after upload completion and before promoting objects to public prefixes.
- Limit sniff bytes for performance but allow deeper inspection up to max_inspect_bytes for ambiguous types.
- Separate quarantine storage prefixes from serving prefixes at the storage layer, not only in application logic.
Failure handling and safeguards
- Verification worker failures retry; persistent failure keeps the object quarantined rather than defaulting to declared type.
- Oversize objects beyond inspection limits receive oversize-unscannable verdict and follow profile rules, typically quarantine or operator review.
- Do not echo full file contents in logs when inspection fails.
Verification and operations
- Measure verdict distribution, quarantine rate, masquerade alerts, and verification latency.
- Test fixtures for pdf-labeled executables, extensionless png, and blocklisted script types.
- Prove serving URLs cannot be issued for quarantine keys through direct storage access tests.
The executable-looking examples in this package are fixtures and acceptance contracts. Run static validation on the package structure and metadata, then implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - WHATWG MIME sniffing informs behavior; teams choose libraries appropriate to their runtime.
- Allowed and blocklisted types are product policy choices, not universal defaults.