filetype

README

tinywasm/filetype

Identifies a file's real type from its bytes. Never decodes, never trusts the client.

A Content-Type header and a file extension are text the client chose — a claim, not evidence. Only the leading bytes decide.

go get github.com/tinywasm/filetype

Why it is tiny

Detection is a comparison of magic-byte prefixes and nothing else. Decoding a PNG merely to check that it is valid would pull in image/png + compress/zlib — hundreds of KB in a WASM binary. This package refuses that trade, which is the whole reason it exists.

Isomorphic: no build tags, no standard library. The same detection runs in the browser (validating before upload) and on the server (validating what arrived), so client and server can never disagree about what a file is.

Usage

import "github.com/tinywasm/filetype"

// Images is the safe default: raster images only, nothing scriptable.
t, err := filetype.Images.Validate(data)
if err != nil {
    return err // "filetype: PDF is not allowed" — the error names what it actually found
}

key := id + t.Ext        // ".png" — the extension comes from the bytes, not from a filename
bucket.Put(key, data, t.MIME)

Or detect without a policy:

t, ok := filetype.Detect(data)
if !ok {
    // No known signature. Reject — never fall back to what the client claimed.
}

Recognized types

Type	Detected	In Images
PNG, JPEG, GIF, WebP	✅	✅
PDF	✅	❌ — add it explicitly if you want it
SVG, HTML	✅	❌ never

SVG and HTML are detected on purpose, so they can be rejected by name instead of disappearing into "unknown". Both can carry JavaScript: served from your own domain, they execute in your origin. Type.Scriptable() reports this.

Build your own policy with NewAllowlist(...). Its zero value accepts nothing — a policy someone forgot to configure must not be permissive.

Testing

gotest

See AGENTS.md for the constraints that govern this library.

Documentation

Overview

Package filetype identifies a file's real type from its leading bytes.

It NEVER decodes content. Detection is a comparison of magic-byte prefixes, so the package costs almost nothing in a WASM binary — decoding a PNG merely to validate it would pull in image/png and compress/zlib, hundreds of KB.

Isomorphic: no build tags, no standard library. The same detection runs in a browser (validating before upload) and on a server (validating what arrived), so client and server can never disagree about what a file is.

The type a client declares — a Content-Type header, a file extension — is a claim, not evidence. Only the bytes are evidence.

Index

• Variables
• type Allowlist
  • func NewAllowlist(t ...Type) Allowlist
  • func (a Allowlist) Validate(data []byte) (Type, error)
• type Type
  • func Detect(data []byte) (t Type, ok bool)
  • func (t Type) Scriptable() bool
  • func (t Type) String() string

Variables

var (
	PNG  = Type{MIME: "image/png", Ext: ".png", /* contains filtered or unexported fields */}
	JPEG = Type{MIME: "image/jpeg", Ext: ".jpg", /* contains filtered or unexported fields */}
	GIF  = Type{MIME: "image/gif", Ext: ".gif", /* contains filtered or unexported fields */}
	WebP = Type{MIME: "image/webp", Ext: ".webp", /* contains filtered or unexported fields */}
	PDF  = Type{MIME: "application/pdf", Ext: ".pdf", /* contains filtered or unexported fields */}

	SVG  = Type{MIME: "image/svg+xml", Ext: ".svg", /* contains filtered or unexported fields */}
	HTML = Type{MIME: "text/html", Ext: ".html", /* contains filtered or unexported fields */}
)

The types this package recognizes.

SVG and HTML are detected ON PURPOSE, so they can be rejected by name instead of vanishing into "unknown". Both can carry JavaScript: served from your own domain, they execute in your origin. Never put them in an Allowlist for user uploads.

var Images = NewAllowlist(PNG, JPEG, GIF, WebP)

Images is the safe default for user uploads: raster images only, nothing scriptable.

Types

type Allowlist

type Allowlist struct {
	// contains filtered or unexported fields
}

Allowlist is the upload policy: which types this site accepts. The zero value accepts nothing — a policy you forgot to configure must not be permissive.

func NewAllowlist

func NewAllowlist(t ...Type) Allowlist

NewAllowlist builds a policy accepting exactly the given types.

func (Allowlist) Validate

func (a Allowlist) Validate(data []byte) (Type, error)

Validate detects data's type and checks it against the policy. The error names the type actually found, so a rejection is diagnosable.

type Type

type Type struct {
	MIME string // "image/png"
	Ext  string // ".png"
	// contains filtered or unexported fields
}

Type is a recognized file type: its real MIME type and canonical extension.

func Detect

func Detect(data []byte) (t Type, ok bool)

Detect returns the type deduced from data's leading bytes. ok=false means no known signature matched — the caller must reject the content, and never fall back to what the client claimed.

func (Type) Scriptable

func (t Type) Scriptable() bool

Scriptable reports whether the type can carry executable code. Serving a scriptable file from your own domain runs that code in your origin.

func (Type) String

func (t Type) String() string

String returns the type's short name ("PNG"), for diagnostics.