@nifrajs/uploads 2.1.0 → 2.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @nifrajs/uploads
 
-File-upload hardening for nifra — magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.
+File-upload hardening for nifra - magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.
 
-Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework — one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
 
 ## Install
 
@@ -19,7 +19,7 @@ MIT
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/detect.d.ts

@@ -1,8 +1,8 @@
 /**
- * Magic-byte file-type detection — trust the bytes, not the `Content-Type` header (which a client
+ * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client
  * sets freely). Reads only the leading bytes; dependency-free + edge-safe. Covers the common upload
  * types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no magic
- * number — handle those explicitly if you accept them).
+ * number - handle those explicitly if you accept them).
  */
 export interface FileType {
     /** Detected MIME type, e.g. `"image/png"`. */

package/dist/detect.js

@@ -1,8 +1,8 @@
 /**
- * Magic-byte file-type detection — trust the bytes, not the `Content-Type` header (which a client
+ * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client
  * sets freely). Reads only the leading bytes; dependency-free + edge-safe. Covers the common upload
  * types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no magic
- * number — handle those explicitly if you accept them).
+ * number - handle those explicitly if you accept them).
  */
 /** Detect a file's type from its magic bytes, or `null` if unrecognized. */
 export function detectFileType(bytes) {
@@ -14,7 +14,7 @@ export function detectFileType(bytes) {
         return { mime: "image/png", ext: "png" };
     if (at(0, 0x47, 0x49, 0x46, 0x38))
         return { mime: "image/gif", ext: "gif" };
-    // RIFF container (bytes 0–3 "RIFF", 8–11 the form type)
+    // RIFF container (bytes 0-3 "RIFF", 8-11 the form type)
     if (at(0, 0x52, 0x49, 0x46, 0x46)) {
         if (at(8, 0x57, 0x45, 0x42, 0x50))
             return { mime: "image/webp", ext: "webp" };
@@ -23,14 +23,14 @@ export function detectFileType(bytes) {
         if (at(8, 0x41, 0x56, 0x49, 0x20))
             return { mime: "video/x-msvideo", ext: "avi" };
     }
-    // ISO-BMFF (`ftyp` box at offset 4) — mp4 / avif / heic / m4a, disambiguated by the major brand.
+    // ISO-BMFF (`ftyp` box at offset 4) - mp4 / avif / heic / m4a, disambiguated by the major brand.
     if (at(4, 0x66, 0x74, 0x79, 0x70)) {
         const brand = String.fromCharCode(bytes[8] ?? 0, bytes[9] ?? 0, bytes[10] ?? 0, bytes[11] ?? 0);
         if (brand === "avif" || brand === "avis")
             return { mime: "image/avif", ext: "avif" };
         if (brand.startsWith("hei") || brand === "mif1")
             return { mime: "image/heic", ext: "heic" };
-        // Audio brands share the ISO-BMFF container but are NOT video — labeling them `video/mp4` would
+        // Audio brands share the ISO-BMFF container but are NOT video - labeling them `video/mp4` would
         // both reject real audio under an `audio/*` allow-list and admit it under `video/*`. `M4A `/`M4B `
         // are AAC audio / audiobooks.
         if (brand === "M4A " || brand === "M4B ")

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 /**
- * `@nifrajs/uploads` — file-upload hardening, dependency-free + edge-safe.
+ * `@nifrajs/uploads` - file-upload hardening, dependency-free + edge-safe.
  *
- * - {@link detectFileType} — sniff the real type from magic bytes (not the client's `Content-Type`).
- * - {@link validateUpload} — size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
+ * - {@link detectFileType} - sniff the real type from magic bytes (not the client's `Content-Type`).
+ * - {@link validateUpload} - size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
  *   `c.boundedBody(maxBytes)` to also bound the read.
- * - {@link signDownloadUrl} / {@link verifyDownloadUrl} — short-TTL, tamper-evident download URLs.
- * - {@link stripImageMetadata} — drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
+ * - {@link signDownloadUrl} / {@link verifyDownloadUrl} - short-TTL, tamper-evident download URLs.
+ * - {@link stripImageMetadata} - drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
  */
 export { detectFileType, type FileType } from "./detect.js";
 export { type SignDownloadUrlOptions, signDownloadUrl, verifyDownloadUrl, } from "./sign.js";

package/dist/index.js

@@ -1,11 +1,11 @@
 /**
- * `@nifrajs/uploads` — file-upload hardening, dependency-free + edge-safe.
+ * `@nifrajs/uploads` - file-upload hardening, dependency-free + edge-safe.
  *
- * - {@link detectFileType} — sniff the real type from magic bytes (not the client's `Content-Type`).
- * - {@link validateUpload} — size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
+ * - {@link detectFileType} - sniff the real type from magic bytes (not the client's `Content-Type`).
+ * - {@link validateUpload} - size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
  *   `c.boundedBody(maxBytes)` to also bound the read.
- * - {@link signDownloadUrl} / {@link verifyDownloadUrl} — short-TTL, tamper-evident download URLs.
- * - {@link stripImageMetadata} — drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
+ * - {@link signDownloadUrl} / {@link verifyDownloadUrl} - short-TTL, tamper-evident download URLs.
+ * - {@link stripImageMetadata} - drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
  */
 export { detectFileType } from "./detect.js";
 export { signDownloadUrl, verifyDownloadUrl, } from "./sign.js";

package/dist/sign.d.ts

@@ -1,5 +1,5 @@
 /**
- * Short-TTL **signed download URLs** — serve an uploaded file back via a tamper-evident, expiring URL
+ * Short-TTL **signed download URLs** - serve an uploaded file back via a tamper-evident, expiring URL
  * (HMAC-SHA256 over the path + query + expiry). WebCrypto only (portable across Bun/Node/Deno/workerd,
  * no `node:crypto`). Verification is constant-time (`crypto.subtle.verify`). Sign a *relative*
  * URL/path; the returned string is relative so it works behind any host. `vexp` / `vsig` are reserved

package/dist/sign.js

@@ -1,5 +1,5 @@
 /**
- * Short-TTL **signed download URLs** — serve an uploaded file back via a tamper-evident, expiring URL
+ * Short-TTL **signed download URLs** - serve an uploaded file back via a tamper-evident, expiring URL
  * (HMAC-SHA256 over the path + query + expiry). WebCrypto only (portable across Bun/Node/Deno/workerd,
  * no `node:crypto`). Verification is constant-time (`crypto.subtle.verify`). Sign a *relative*
  * URL/path; the returned string is relative so it works behind any host. `vexp` / `vsig` are reserved
@@ -7,7 +7,7 @@
  */
 const ENC = new TextEncoder();
 const DUMMY_BASE = "http://localhost"; // lets us parse a relative path/URL with the WHATWG URL parser
-// 256-bit secret floor — mirrors @nifrajs/core's HMAC guard. This package is deliberately
+// 256-bit secret floor - mirrors @nifrajs/core's HMAC guard. This package is deliberately
 // dependency-free (ships its own crypto), so the constant is inlined rather than imported.
 const MIN_SECRET_BYTES = 32;
 const importKey = (secret) => {

package/dist/strip.d.ts

@@ -1,14 +1,14 @@
 /**
- * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it — decoders don't carry
+ * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it - decoders don't carry
  * embedded metadata through, so a decode→encode round-trip drops it (and normalizes the format).
  *
  * Backend-agnostic: pass any `@nifrajs/image` backend (`bunImageBackend`, `sharpImageBackend`,
- * `wasmImageBackend`) — the structural type below matches them, so this package takes **no** dependency
+ * `wasmImageBackend`) - the structural type below matches them, so this package takes **no** dependency
  * on `@nifrajs/image`. Run server-side (the codecs are Node/Bun-only); validate the upload first
  * (`validateUpload`) so you only re-encode real images.
  */
 type StripFormat = "webp" | "jpeg" | "png";
-/** The slice of `@nifrajs/image`'s `ImageBackend` this needs — `probe` for dims/format, `transform` to re-encode. */
+/** The slice of `@nifrajs/image`'s `ImageBackend` this needs - `probe` for dims/format, `transform` to re-encode. */
 export interface ImageReencoder {
     probe(bytes: Uint8Array): Promise<{
         readonly width: number;
@@ -27,7 +27,7 @@ export interface ImageReencoder {
 export interface StripImageMetadataOptions {
     /** Output format. Default: keep png/jpeg, else re-encode to webp. */
     readonly format?: StripFormat;
-    /** Encode quality (1–100). Default 82. */
+    /** Encode quality (1-100). Default 82. */
     readonly quality?: number;
 }
 /** Re-encode an image to its intrinsic size, dropping all embedded metadata. Returns clean bytes. */

package/dist/strip.js

@@ -1,9 +1,9 @@
 /**
- * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it — decoders don't carry
+ * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it - decoders don't carry
  * embedded metadata through, so a decode→encode round-trip drops it (and normalizes the format).
  *
  * Backend-agnostic: pass any `@nifrajs/image` backend (`bunImageBackend`, `sharpImageBackend`,
- * `wasmImageBackend`) — the structural type below matches them, so this package takes **no** dependency
+ * `wasmImageBackend`) - the structural type below matches them, so this package takes **no** dependency
  * on `@nifrajs/image`. Run server-side (the codecs are Node/Bun-only); validate the upload first
  * (`validateUpload`) so you only re-encode real images.
  */

package/dist/validate.d.ts

@@ -18,7 +18,7 @@ export type UploadResult = {
 export interface ValidateUploadOptions {
     /** Max byte length. A `Blob` over this is rejected without reading it. */
     readonly maxBytes: number;
-    /** Allowed MIME types — exact (`"image/png"`) or a `image/*` wildcard. Omit ⇒ any recognized type. */
+    /** Allowed MIME types - exact (`"image/png"`) or a `image/*` wildcard. Omit ⇒ any recognized type. */
     readonly accept?: readonly string[];
 }
 /** Validate uploaded bytes/Blob: size cap + magic-byte type sniff against an optional allow-list. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/uploads",
-  "version": "2.1.0",
-  "description": "File-upload hardening for nifra — magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.",
+  "version": "2.3.0",
+  "description": "File-upload hardening for nifra - magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.",
   "keywords": [
     "bun",
     "typescript",

package/src/detect.ts

@@ -1,8 +1,8 @@
 /**
- * Magic-byte file-type detection — trust the bytes, not the `Content-Type` header (which a client
+ * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client
  * sets freely). Reads only the leading bytes; dependency-free + edge-safe. Covers the common upload
  * types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no magic
- * number — handle those explicitly if you accept them).
+ * number - handle those explicitly if you accept them).
  */
 
 export interface FileType {
@@ -23,19 +23,19 @@ export function detectFileType(bytes: Uint8Array): FileType | null {
     return { mime: "image/png", ext: "png" }
   if (at(0, 0x47, 0x49, 0x46, 0x38)) return { mime: "image/gif", ext: "gif" }
 
-  // RIFF container (bytes 0–3 "RIFF", 8–11 the form type)
+  // RIFF container (bytes 0-3 "RIFF", 8-11 the form type)
   if (at(0, 0x52, 0x49, 0x46, 0x46)) {
     if (at(8, 0x57, 0x45, 0x42, 0x50)) return { mime: "image/webp", ext: "webp" }
     if (at(8, 0x57, 0x41, 0x56, 0x45)) return { mime: "audio/wav", ext: "wav" }
     if (at(8, 0x41, 0x56, 0x49, 0x20)) return { mime: "video/x-msvideo", ext: "avi" }
   }
 
-  // ISO-BMFF (`ftyp` box at offset 4) — mp4 / avif / heic / m4a, disambiguated by the major brand.
+  // ISO-BMFF (`ftyp` box at offset 4) - mp4 / avif / heic / m4a, disambiguated by the major brand.
   if (at(4, 0x66, 0x74, 0x79, 0x70)) {
     const brand = String.fromCharCode(bytes[8] ?? 0, bytes[9] ?? 0, bytes[10] ?? 0, bytes[11] ?? 0)
     if (brand === "avif" || brand === "avis") return { mime: "image/avif", ext: "avif" }
     if (brand.startsWith("hei") || brand === "mif1") return { mime: "image/heic", ext: "heic" }
-    // Audio brands share the ISO-BMFF container but are NOT video — labeling them `video/mp4` would
+    // Audio brands share the ISO-BMFF container but are NOT video - labeling them `video/mp4` would
     // both reject real audio under an `audio/*` allow-list and admit it under `video/*`. `M4A `/`M4B `
     // are AAC audio / audiobooks.
     if (brand === "M4A " || brand === "M4B ") return { mime: "audio/mp4", ext: "m4a" }

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * `@nifrajs/uploads` — file-upload hardening, dependency-free + edge-safe.
+ * `@nifrajs/uploads` - file-upload hardening, dependency-free + edge-safe.
  *
- * - {@link detectFileType} — sniff the real type from magic bytes (not the client's `Content-Type`).
- * - {@link validateUpload} — size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
+ * - {@link detectFileType} - sniff the real type from magic bytes (not the client's `Content-Type`).
+ * - {@link validateUpload} - size cap + magic-byte type allow-list. Pair with `@nifrajs/core`'s
  *   `c.boundedBody(maxBytes)` to also bound the read.
- * - {@link signDownloadUrl} / {@link verifyDownloadUrl} — short-TTL, tamper-evident download URLs.
- * - {@link stripImageMetadata} — drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
+ * - {@link signDownloadUrl} / {@link verifyDownloadUrl} - short-TTL, tamper-evident download URLs.
+ * - {@link stripImageMetadata} - drop EXIF/GPS by re-encoding via any `@nifrajs/image` backend.
  */
 export { detectFileType, type FileType } from "./detect.ts"
 export {

package/src/sign.ts

@@ -1,5 +1,5 @@
 /**
- * Short-TTL **signed download URLs** — serve an uploaded file back via a tamper-evident, expiring URL
+ * Short-TTL **signed download URLs** - serve an uploaded file back via a tamper-evident, expiring URL
  * (HMAC-SHA256 over the path + query + expiry). WebCrypto only (portable across Bun/Node/Deno/workerd,
  * no `node:crypto`). Verification is constant-time (`crypto.subtle.verify`). Sign a *relative*
  * URL/path; the returned string is relative so it works behind any host. `vexp` / `vsig` are reserved
@@ -9,7 +9,7 @@
 const ENC = new TextEncoder()
 const DUMMY_BASE = "http://localhost" // lets us parse a relative path/URL with the WHATWG URL parser
 
-// 256-bit secret floor — mirrors @nifrajs/core's HMAC guard. This package is deliberately
+// 256-bit secret floor - mirrors @nifrajs/core's HMAC guard. This package is deliberately
 // dependency-free (ships its own crypto), so the constant is inlined rather than imported.
 const MIN_SECRET_BYTES = 32
 

package/src/strip.ts

@@ -1,16 +1,16 @@
 /**
- * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it — decoders don't carry
+ * Strip EXIF/GPS/metadata from an uploaded image by **re-encoding** it - decoders don't carry
  * embedded metadata through, so a decode→encode round-trip drops it (and normalizes the format).
  *
  * Backend-agnostic: pass any `@nifrajs/image` backend (`bunImageBackend`, `sharpImageBackend`,
- * `wasmImageBackend`) — the structural type below matches them, so this package takes **no** dependency
+ * `wasmImageBackend`) - the structural type below matches them, so this package takes **no** dependency
  * on `@nifrajs/image`. Run server-side (the codecs are Node/Bun-only); validate the upload first
  * (`validateUpload`) so you only re-encode real images.
  */
 
 type StripFormat = "webp" | "jpeg" | "png"
 
-/** The slice of `@nifrajs/image`'s `ImageBackend` this needs — `probe` for dims/format, `transform` to re-encode. */
+/** The slice of `@nifrajs/image`'s `ImageBackend` this needs - `probe` for dims/format, `transform` to re-encode. */
 export interface ImageReencoder {
   probe(
     bytes: Uint8Array,
@@ -26,7 +26,7 @@ export interface ImageReencoder {
 export interface StripImageMetadataOptions {
   /** Output format. Default: keep png/jpeg, else re-encode to webp. */
   readonly format?: StripFormat
-  /** Encode quality (1–100). Default 82. */
+  /** Encode quality (1-100). Default 82. */
   readonly quality?: number
 }
 

package/src/validate.ts

@@ -18,7 +18,7 @@ export type UploadResult =
 export interface ValidateUploadOptions {
   /** Max byte length. A `Blob` over this is rejected without reading it. */
   readonly maxBytes: number
-  /** Allowed MIME types — exact (`"image/png"`) or a `image/*` wildcard. Omit ⇒ any recognized type. */
+  /** Allowed MIME types - exact (`"image/png"`) or a `image/*` wildcard. Omit ⇒ any recognized type. */
   readonly accept?: readonly string[]
 }