feat(uploader): verify uploaded MIME against magic bytes (closes #639)

[61465]

What

Adds magic-byte verification to the uploader so that bucket-level
allowed_mime_types restrictions catch files whose declared MIME does not
match the actual signature.

Fixes #639 — the reporter's
case was uploading a renamed .gif with Content-Type: image/jpeg to a
bucket restricted to image/jpeg,image/png; today's validateMimeType
accepts it because only the client-declared value is checked.

How

Pre-existing path (unchanged):
validateMimeType(mimeType, allowedMimeTypes) — compares the declared
Content-Type / multipart field against the bucket's allowlist.

Added path (src/storage/validators/file-signature.ts):

1. detectMimeFromBuffer(buf) — 23 signatures covering images, documents,
   archives, audio/video, and executables. Refine functions distinguish
   RIFF/WEBP from RIFF/WAVE, and ISO BMFF ftyp sub-brands
   (mp4 / heic / avif / mov / 3gp / m4a / webm). Returns undefined on
   unknown signatures so novel formats continue to work.
2. mimeFamiliesMatch(detected, declared) — intentionally loose:
   image/jpg == image/jpeg, application/zip accepted for OOXML office
   MIMEs, application/x-cfb accepted for legacy OLE2 formats.
3. wrapWithSignatureDetection(source) — returns a PassThrough and a
   promise that resolves with the detected MIME once the first 4 KiB has
   flowed. No bytes are swallowed; the backend sees the stream unmodified.

Wiring in uploader.ts (after the existing declared-MIME check):

if (allowedMimeTypes?.length) {
  const { stream, detected } = wrapWithSignatureDetection(body)
  body = stream
  detected.then((actualMime) => {
    if (actualMime && !mimeFamiliesMatch(actualMime, mimeType)) {
      stream.destroy(ERRORS.InvalidMimeType(`${actualMime} (declared as ${mimeType})`))
    }
  })
}

Buckets with no mimetype restriction stay on the fast path — no wrapping,
no extra CPU, zero behavioral change.

Why this design

• Pure helper, zero new deps. Avoids pulling in file-type (ESM-only in
  current versions) and keeps the supply-chain surface flat.
• Pure helper, no logger/db/config imports. Follows the pattern that
  worked on JWK not used in signObjectURL #629 — anything circular is caught at compile time.
• Stream-safe. Peek-and-flush PassThrough; the backend never sees a
  truncated or delayed body. Max 4 KiB extra buffered.
• Fail-closed, 415-compatible. Mismatch raises ERRORS.InvalidMimeType,
  same error code and HTTP status (415) as a header-level rejection, so
  existing clients already handle it.
• Loose family matching. image/jpg → image/jpeg, zip → OOXML office,
  x-cfb → legacy office. Prevents false positives on legitimate uploads
  while still catching the attack cases from the report.

Tests

41 vitest cases in src/storage/validators/file-signature.test.ts:

• Detection — real-signature match for each supported format (23 cases).
• Edge cases — empty buffer, 1-byte buffer, unknown prefix.
• False-positive defense — RIFF with an unknown form chunk, ftyp with
  an unknown brand (both must return undefined, not fall back to the
  entry's default MIME).
• Family matching — alias cases (jpg/jpeg, OOXML/zip, OLE2/x-cfb) and
  the eight security-relevant mismatch scenarios the fix is meant to catch:
  • renamed .gif → image/jpeg (the exact mime-type does not check uploaded files, only the filename #639 repro)
  • polyglot JPG claiming to be text/html
  • PE executable declared as application/pdf
  • ELF executable declared as image/jpeg
  • zip claiming to be image/png
  • gzip claiming to be image/jpeg
  • mp4 claiming to be image/jpeg

Also verified mime-type.test.ts still passes (37/37) — no behavior change
to the existing declared-MIME check.

Run:

npx vitest run --config vitest.unit.config.ts src/storage/validators/file-signature.test.ts
# Test Files  1 passed (1)
#      Tests  41 passed (41)

Impact

• Buckets with no allowed_mime_types → zero code-path change.
• Buckets with restrictions → one extra PassThrough + 4 KiB peek per
  upload. Negligible overhead vs. the network / storage write cost.
• Detection failure (unknown signature) is non-fatal — the declared MIME
  stands. We only refuse when we're certain the actual family is wrong.

Security notes

This closes a real file-upload hardening gap. Common attack cases this now
catches:

1. Payload smuggling — upload an EXE/ELF declared as image/png to a
   bucket that only allows images, then trigger it from a victim client.
2. Polyglot files — crafted files that are valid JPG and valid HTML.
3. Backup exfil via image buckets — upload a zip (contains db dump)
   declared as image/jpeg.

Report: #639 by @flogesell,
open 853 days.

---

Prior work in this repo for context:

• fix: auto-select url-signing JWK from JWT_JWKS (closes #629) #1488 (JWK auto-selection, closes JWK not used in signObjectURL #629) — same pure-helper pattern used here.