@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/utils/hash/sha256.ts

@@ -0,0 +1,179 @@
+// biome-ignore-all lint/style/noNonNullAssertion: fixed-bounds reads over Uint8/Uint32Array in the SHA-256 hot loop are always defined; asserting avoids per-read branches.
+
+/**
+ * Pure-JS incremental SHA-256 over a `Blob`/`File`.
+ *
+ * Web Crypto (`crypto.subtle.digest`) has no streaming/incremental API, so it
+ * must buffer the whole file in memory. This implementation reads the blob in
+ * bounded slices and folds each into the digest state, so memory stays flat
+ * regardless of file size.
+ *
+ * The whole algorithm lives inside a single self-contained function with no
+ * external references (constants and helpers are declared locally). That lets
+ * {@link ./index} stringify it with `Function.prototype.toString` and run it
+ * verbatim inside a Web Worker, keeping large-file hashing off the main thread.
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+
+/** Default slice size fed to the hasher: 8 MiB. */
+export const DEFAULT_HASH_CHUNK_SIZE = 8 * 1024 * 1024
+
+/**
+ * Compute the lowercase hex SHA-256 digest of `blob`, reading it in bounded
+ * slices so peak memory is `~chunkSize` rather than the whole file.
+ *
+ * @param blob - Source bytes (a `File` is a `Blob`).
+ * @param opts.chunkSize - Slice size in bytes. Defaults to {@link DEFAULT_HASH_CHUNK_SIZE}.
+ * @param opts.signal - Optional abort signal, checked between slices.
+ * @returns 64-char lowercase hex digest.
+ */
+export async function sha256HexOfBlob(
+  blob: Blob,
+  opts?: { chunkSize?: number; signal?: AbortSignal },
+): Promise<string> {
+  const chunkSize = opts?.chunkSize && opts.chunkSize > 0 ? opts.chunkSize : 8 * 1024 * 1024
+  const signal = opts?.signal
+
+  // Round constants (first 32 bits of the fractional parts of the cube roots
+  // of the first 64 primes).
+  const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+  ])
+
+  let h0 = 0x6a09e667
+  let h1 = 0xbb67ae85
+  let h2 = 0x3c6ef372
+  let h3 = 0xa54ff53a
+  let h4 = 0x510e527f
+  let h5 = 0x9b05688c
+  let h6 = 0x1f83d9ab
+  let h7 = 0x5be0cd19
+
+  const w = new Uint32Array(64)
+  const block = new Uint8Array(64)
+  let blockLen = 0
+  let totalLen = 0
+
+  const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n))
+
+  const compress = (): void => {
+    for (let i = 0; i < 16; i++) {
+      const j = i * 4
+      w[i] = ((block[j]! << 24) | (block[j + 1]! << 16) | (block[j + 2]! << 8) | block[j + 3]!) >>> 0
+    }
+    for (let i = 16; i < 64; i++) {
+      const x15 = w[i - 15]!
+      const x2 = w[i - 2]!
+      const s0 = rotr(x15, 7) ^ rotr(x15, 18) ^ (x15 >>> 3)
+      const s1 = rotr(x2, 17) ^ rotr(x2, 19) ^ (x2 >>> 10)
+      w[i] = (w[i - 16]! + s0 + w[i - 7]! + s1) >>> 0
+    }
+
+    let a = h0
+    let b = h1
+    let c = h2
+    let d = h3
+    let e = h4
+    let f = h5
+    let g = h6
+    let h = h7
+
+    for (let i = 0; i < 64; i++) {
+      const bigS1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)
+      const ch = (e & f) ^ (~e & g)
+      const t1 = (h + bigS1 + ch + K[i]! + w[i]!) >>> 0
+      const bigS0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)
+      const maj = (a & b) ^ (a & c) ^ (b & c)
+      const t2 = (bigS0 + maj) >>> 0
+      h = g
+      g = f
+      f = e
+      e = (d + t1) >>> 0
+      d = c
+      c = b
+      b = a
+      a = (t1 + t2) >>> 0
+    }
+
+    h0 = (h0 + a) >>> 0
+    h1 = (h1 + b) >>> 0
+    h2 = (h2 + c) >>> 0
+    h3 = (h3 + d) >>> 0
+    h4 = (h4 + e) >>> 0
+    h5 = (h5 + f) >>> 0
+    h6 = (h6 + g) >>> 0
+    h7 = (h7 + h) >>> 0
+  }
+
+  const update = (bytes: Uint8Array): void => {
+    totalLen += bytes.length
+    let off = 0
+
+    // Top up a partially filled block from a previous slice.
+    if (blockLen > 0) {
+      const take = Math.min(64 - blockLen, bytes.length)
+      block.set(bytes.subarray(0, take), blockLen)
+      blockLen += take
+      off = take
+      if (blockLen === 64) {
+        compress()
+        blockLen = 0
+      }
+    }
+
+    // Consume whole 64-byte blocks directly from the slice.
+    while (bytes.length - off >= 64) {
+      block.set(bytes.subarray(off, off + 64), 0)
+      compress()
+      off += 64
+    }
+
+    // Stash the trailing remainder for the next slice / finalization.
+    if (off < bytes.length) {
+      const rest = bytes.subarray(off)
+      block.set(rest, 0)
+      blockLen = rest.length
+    }
+  }
+
+  const size = blob.size
+  for (let pos = 0; pos < size; pos += chunkSize) {
+    if (signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+    const end = Math.min(size, pos + chunkSize)
+    const buf = await blob.slice(pos, end).arrayBuffer()
+    update(new Uint8Array(buf))
+  }
+
+  // Finalize: append 0x80, pad with zeros, then the 64-bit big-endian bit length.
+  const lenBits = totalLen * 8
+  const hi = Math.floor(lenBits / 0x100000000) >>> 0
+  const lo = lenBits >>> 0
+
+  block[blockLen++] = 0x80
+  if (blockLen > 56) {
+    while (blockLen < 64) block[blockLen++] = 0
+    compress()
+    blockLen = 0
+  }
+  while (blockLen < 56) block[blockLen++] = 0
+  block[56] = (hi >>> 24) & 0xff
+  block[57] = (hi >>> 16) & 0xff
+  block[58] = (hi >>> 8) & 0xff
+  block[59] = hi & 0xff
+  block[60] = (lo >>> 24) & 0xff
+  block[61] = (lo >>> 16) & 0xff
+  block[62] = (lo >>> 8) & 0xff
+  block[63] = lo & 0xff
+  compress()
+
+  const toHex = (x: number): string => (x >>> 0).toString(16).padStart(8, '0')
+  return toHex(h0) + toHex(h1) + toHex(h2) + toHex(h3) + toHex(h4) + toHex(h5) + toHex(h6) + toHex(h7)
+}

package/src/core/utils/id.ts

@@ -1,3 +1,35 @@
+/**
+ * Generate a unique upload ID.
+ *
+ * Format: `upload_<unix-ms>_<uuid-v4>`. The UUID is produced by
+ * {@link Crypto.randomUUID} on platforms that expose it (Node >= 14.17,
+ * all modern browsers in secure contexts). On legacy runtimes we fall
+ * back to {@link Crypto.getRandomValues} + manual v4 formatting.
+ *
+ * Throws if no CSPRNG is reachable; `Math.random()` is deliberately not used,
+ * since predictable IDs can collide and leak creation ordering.
+ */
 export function generateId(): string {
-  return `upload_${Date.now()}_${Math.random().toString(36).slice(2)}`
+  return `upload_${Date.now()}_${randomUUIDv4()}`
+}
+
+function randomUUIDv4(): string {
+  const c: Crypto | undefined = (globalThis as { crypto?: Crypto }).crypto
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID()
+  }
+  if (c && typeof c.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16)
+    c.getRandomValues(bytes)
+    // RFC 4122 §4.4 — set version (4) and variant (10xx). `bytes` is fixed at
+    // length 16, so every index is in bounds; `?? 0` satisfies the checker.
+    const b6 = bytes[6] ?? 0
+    const b8 = bytes[8] ?? 0
+    bytes[6] = (b6 & 0x0f) | 0x40
+    bytes[8] = (b8 & 0x3f) | 0x80
+    const hex: string[] = []
+    for (let i = 0; i < bytes.length; i++) hex.push((bytes[i] ?? 0).toString(16).padStart(2, '0'))
+    return `${hex.slice(0, 4).join('')}-${hex.slice(4, 6).join('')}-${hex.slice(6, 8).join('')}-${hex.slice(8, 10).join('')}-${hex.slice(10, 16).join('')}`
+  }
+  throw new Error('[duck-upload] No CSPRNG available: crypto.randomUUID and crypto.getRandomValues both missing')
 }

package/src/core/utils/index.ts

@@ -1,6 +1,15 @@
-export * from './async'
-export * from './constants'
-export * from './emitter'
-export * from './fingerprint'
-export * from './guards'
-export * from './id'
+export { sleep } from './async'
+export {
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_MAX_CONCURRENT_UPLOADS,
+  DEFAULT_MAX_ITEMS,
+  DEFAULT_PROGRESS_THROTTLE_MS,
+  DEFAULT_RETRY_DELAY_BASE_MS,
+  DEFAULT_RETRY_DELAY_MAX_MS,
+} from './constants'
+export type { Emitter } from './emitter'
+export { createTypedEmitter } from './emitter'
+export { computeFingerprint, fingerprintMatches } from './fingerprint'
+export { isRecord, stripDangerousKeys } from './guards'
+export { DEFAULT_HASH_CHUNK_SIZE, hashBlob, sha256HexOfBlob } from './hash'
+export { generateId } from './id'

package/src/core/utils/mime-sniff.ts

@@ -0,0 +1,119 @@
+/**
+ * Inspect the first bytes of `bytes` and return the canonical MIME type
+ * for the format if recognised, or `null` if unknown.
+ *
+ * 12 bytes is sufficient for every signature handled here; callers may
+ * pass a longer slice but anything beyond byte 11 is ignored.
+ */
+export function sniffMime(bytes: Uint8Array): string | null {
+  const n = bytes.length
+
+  // JPEG: FF D8 FF
+  if (n >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return 'image/jpeg'
+  }
+
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    n >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47 &&
+    bytes[4] === 0x0d &&
+    bytes[5] === 0x0a &&
+    bytes[6] === 0x1a &&
+    bytes[7] === 0x0a
+  ) {
+    return 'image/png'
+  }
+
+  // GIF: 47 49 46 38 ("GIF8")
+  if (n >= 4 && bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) {
+    return 'image/gif'
+  }
+
+  // PDF: 25 50 44 46 ("%PDF")
+  if (n >= 4 && bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) {
+    return 'application/pdf'
+  }
+
+  // WebP: bytes 0-3 = "RIFF" and bytes 8-11 = "WEBP"
+  if (
+    n >= 12 &&
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  ) {
+    return 'image/webp'
+  }
+
+  // MP4 / ISO BMFF: bytes 4-7 = "ftyp"
+  if (n >= 8 && bytes[4] === 0x66 && bytes[5] === 0x74 && bytes[6] === 0x79 && bytes[7] === 0x70) {
+    return 'video/mp4'
+  }
+
+  // WebM / Matroska EBML header: 1A 45 DF A3
+  if (n >= 4 && bytes[0] === 0x1a && bytes[1] === 0x45 && bytes[2] === 0xdf && bytes[3] === 0xa3) {
+    return 'video/webm'
+  }
+
+  // ZIP-family (DOCX/XLSX/PPTX/APK/JAR/EPUB share this): 50 4B 03 04
+  if (n >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04) {
+    return 'application/zip'
+  }
+
+  // MP3: ID3v2 tag (49 44 33) or MPEG frame sync (FF FB / FF F3 / FF F2)
+  if (n >= 3 && bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33) {
+    return 'audio/mpeg'
+  }
+  if (n >= 2 && bytes[0] === 0xff && (bytes[1] === 0xfb || bytes[1] === 0xf3 || bytes[1] === 0xf2)) {
+    return 'audio/mpeg'
+  }
+
+  return null
+}
+
+/**
+ * Compare a sniffed MIME type against a claimed one. Returns `true` when
+ * they refer to the same format, `false` on conflict. `null` sniff is
+ * always treated as a match (unknown formats are not a deny condition).
+ *
+ * Comparison is loose by design  `image/jpg` vs `image/jpeg`, ZIP-based
+ * Office formats vs `application/zip`, etc. all need to be tolerated.
+ */
+export function mimeMatches(claimed: string, sniffed: string | null): boolean {
+  if (!sniffed) return true
+  const c = claimed.toLowerCase().trim()
+  const s = sniffed.toLowerCase().trim()
+  if (c === s) return true
+  if (c === '' || c === 'application/octet-stream') return true
+
+  // Tolerate ZIP-based document formats  the magic bytes only say "this
+  // is a ZIP container", which is the truthful low-level answer. Any
+  // claimed Office / OpenDocument / JAR / APK / EPUB type is consistent.
+  if (s === 'application/zip') {
+    if (
+      c.startsWith('application/vnd.openxmlformats-officedocument.') ||
+      c.startsWith('application/vnd.oasis.opendocument.') ||
+      c === 'application/epub+zip' ||
+      c === 'application/java-archive' ||
+      c === 'application/vnd.android.package-archive'
+    ) {
+      return true
+    }
+  }
+
+  // JPEG common aliases.
+  if (s === 'image/jpeg' && (c === 'image/jpg' || c === 'image/pjpeg')) return true
+
+  return false
+}
+
+/** Module-level dedup set for one-time-per-session warnings. @internal */
+export const __mimeWarnings = new Set<string>()

package/src/core/utils/sanitize-filename.ts

@@ -0,0 +1,85 @@
+export type FilenameRejectReason = 'reserved' | 'too-long' | 'empty' | 'path-sep'
+
+export type SanitizeFilenameResult =
+  | { safe: true; normalised: string }
+  | { safe: false; normalised: string; reason: FilenameRejectReason }
+
+// TODO: use regex
+const RESERVED_WINDOWS_NAMES = new Set([
+  'CON',
+  'PRN',
+  'AUX',
+  'NUL',
+  'COM1',
+  'COM2',
+  'COM3',
+  'COM4',
+  'COM5',
+  'COM6',
+  'COM7',
+  'COM8',
+  'COM9',
+  'LPT1',
+  'LPT2',
+  'LPT3',
+  'LPT4',
+  'LPT5',
+  'LPT6',
+  'LPT7',
+  'LPT8',
+  'LPT9',
+])
+
+function stripControlChars(s: string): string {
+  let out = ''
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c >= 0x20 && c !== 0x7f) out += s[i]
+  }
+  return out
+}
+
+/**
+ * Normalise and validate an untrusted filename. Returns
+ * `{ safe: true, normalised }` when the name is safe to forward to a backend,
+ * or `{ safe: false, normalised, reason }` with the partial cleanup for
+ * diagnostics. Pure and synchronous.
+ */
+export function sanitizeFilename(name: string): SanitizeFilenameResult {
+  // NFKC normalise.
+  let n = name.normalize('NFKC')
+
+  // Strip control chars and DEL.
+  n = stripControlChars(n)
+
+  // Strip leading dashes.
+  while (n.startsWith('-')) n = n.slice(1)
+
+  // Strip trailing dots and spaces (Windows behaviour).
+  while (n.length > 0 && (n.endsWith('.') || n.endsWith(' '))) n = n.slice(0, -1)
+
+  // Reject if nothing survived.
+  if (n.length === 0) {
+    return { safe: false, normalised: n, reason: 'empty' }
+  }
+
+  // Path separators must never reach here.
+  if (n.includes('/') || n.includes('\\')) {
+    return { safe: false, normalised: n, reason: 'path-sep' }
+  }
+
+  // Length cap.
+  if (n.length > 255) {
+    return { safe: false, normalised: n, reason: 'too-long' }
+  }
+
+  // Reserved Windows device names — match the base (before the first dot),
+  // case-insensitive. `CON.txt`, `nul`, `COM1.tar.gz` all reject.
+  const dot = n.indexOf('.')
+  const base = (dot === -1 ? n : n.slice(0, dot)).toUpperCase()
+  if (RESERVED_WINDOWS_NAMES.has(base)) {
+    return { safe: false, normalised: n, reason: 'reserved' }
+  }
+
+  return { safe: true, normalised: n }
+}

package/src/core/utils/url-safety.ts

@@ -0,0 +1,156 @@
+/**
+ * SSRF guards for backend-supplied upload URLs.
+ *
+ * Every URL that arrives from a non-trusted backend (presigned POST,
+ * presigned PUT, multipart part URLs) must pass through
+ * `validateUploadUrl` before it reaches the transport. The guard
+ * blocks:
+ *
+ * - Empty / non-string / malformed URLs
+ * - `..` path-traversal segments (URL parser would normalize them away)
+ * - Non-http(s) protocols (`file:`, `javascript:`, `data:`)
+ * - IP literals pointing at loopback / RFC1918 / link-local /
+ *   cloud-metadata / CGNAT / multicast / broadcast addresses
+ * - IPv6 embedded IPv4 (mapped, compat, 6to4, NAT64) carrying any of the above
+ *
+ * DNS rebinding is out of scope for a client-side check.
+ */
+
+function hexTailToDottedQuad(tail: string): string | null {
+  const m = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(tail)
+  if (!m || m[1] === undefined || m[2] === undefined) return null
+  const hi = parseInt(m[1], 16)
+  const lo = parseInt(m[2], 16)
+  if (!Number.isFinite(hi) || !Number.isFinite(lo)) return null
+  if (hi < 0 || hi > 0xffff || lo < 0 || lo > 0xffff) return null
+  return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`
+}
+
+/**
+ * Returns true when `host` is a literal IP address in one of the
+ * private / loopback / cloud-metadata ranges. Hostnames that aren't IP
+ * literals return false.
+ */
+export function isPrivateHost(host: string): boolean {
+  let h = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+  if (h.endsWith('.')) h = h.slice(0, -1)
+
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h)
+  if (v4) {
+    const a = Number(v4[1])
+    const b = Number(v4[2])
+    const c = Number(v4[3])
+    const d = Number(v4[4])
+    if (a > 255 || b > 255 || c > 255 || d > 255) return false
+    if (a === 127) return true // 127.0.0.0/8 loopback
+    if (a === 10) return true // 10.0.0.0/8 RFC1918
+    if (a === 192 && b === 168) return true // 192.168.0.0/16 RFC1918
+    if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12 RFC1918
+    if (a === 169 && b === 254) return true // 169.254.0.0/16 link-local + AWS metadata
+    if (a === 0) return true // 0.0.0.0/8 this-network
+    if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 CGNAT
+    if (a >= 224 && a <= 239) return true // 224.0.0.0/4 multicast
+    if (a >= 240) return true // 240.0.0.0/4 reserved + broadcast
+    return false
+  }
+
+  if (h.includes(':')) {
+    const lower = h.toLowerCase()
+    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true
+    if (lower === '::' || lower === '0:0:0:0:0:0:0:0') return true
+    if (/^f[cd][0-9a-f]{0,2}:/.test(lower)) return true // fc00::/7
+    if (/^fe[89ab][0-9a-f]?:/.test(lower)) return true // fe80::/10
+    if (/^ff[0-9a-f]{0,2}:/.test(lower)) return true // ff00::/8 multicast
+
+    let mappedTail: string | null = null
+    if (lower.startsWith('::ffff:')) mappedTail = lower.slice(7)
+    else if (lower.startsWith('0:0:0:0:0:ffff:')) mappedTail = lower.slice(15)
+    if (mappedTail !== null) {
+      if (mappedTail.includes('.')) return isPrivateHost(mappedTail)
+      const dotted = hexTailToDottedQuad(mappedTail)
+      if (dotted) return isPrivateHost(dotted)
+      return false
+    }
+
+    if (lower.startsWith('::') && lower.includes('.')) {
+      const tail = lower.slice(2)
+      if (/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(tail)) return isPrivateHost(tail)
+    }
+
+    if (lower.startsWith('2002:')) {
+      const m = /^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})(?::|$)/.exec(lower)
+      if (m) {
+        const dotted = hexTailToDottedQuad(`${m[1]}:${m[2]}`)
+        if (dotted) return isPrivateHost(dotted)
+      }
+    }
+
+    if (lower.startsWith('64:ff9b:') || lower.startsWith('0064:ff9b:')) {
+      const tail = lower.startsWith('0064:') ? lower.slice(10) : lower.slice(8)
+      if (tail.includes('.')) {
+        const v4match = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(tail)
+        if (v4match?.[1] !== undefined) return isPrivateHost(v4match[1])
+      }
+      const groups = tail.split(':').filter((g) => g.length > 0)
+      if (groups.length >= 2) {
+        const dotted = hexTailToDottedQuad(`${groups[groups.length - 2]}:${groups[groups.length - 1]}`)
+        if (dotted) return isPrivateHost(dotted)
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+/**
+ * Throw-on-reject URL guard. Use from any strategy whose backend may
+ * return adversarial / compromised URLs. `caller` is a short label
+ * ('multipart.signPart', 'post.intent', etc.) included in error messages
+ * so logs name the source.
+ */
+export function validateUploadUrl(
+  rawUrl: string,
+  caller: string,
+  opts: { allowedHosts?: string[]; allowPrivateHosts?: boolean } = {},
+): void {
+  if (typeof rawUrl !== 'string' || rawUrl.length === 0) {
+    throw new Error(`${caller} returned an invalid URL (empty or non-string)`)
+  }
+
+  // Cap raw URL length. Real presigned URLs are well under 4 KB; anything
+  // larger is either a server bug or an attacker probing the parser.
+  if (rawUrl.length > 8192) {
+    throw new Error(`${caller} URL exceeds 8192-byte length cap`)
+  }
+
+  if (rawUrl.includes('..')) {
+    throw new Error(`${caller} URL contains forbidden ".." segment`)
+  }
+
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    throw new Error(`${caller} returned a malformed URL`)
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`${caller} URL has forbidden protocol "${parsed.protocol}"`)
+  }
+
+  if (opts.allowedHosts && opts.allowedHosts.length > 0) {
+    const host = parsed.host.toLowerCase()
+    const list = opts.allowedHosts.map((h) => h.toLowerCase())
+    if (!list.includes(host)) {
+      throw new Error(`${caller} URL host is not in the configured allow-list`)
+    }
+  }
+
+  if (!opts.allowPrivateHosts) {
+    if (isPrivateHost(parsed.hostname)) {
+      throw new Error(`${caller} URL points to a private/loopback host`)
+    }
+  }
+}

package/src/react/__tests__/use-dropzone.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'vitest'
+import { fileMatchesAccept, matchesAcceptToken, selectFiles } from '../use-dropzone'
+
+function f(name: string, type = ''): File {
+  return new File(['x'], name, { type })
+}
+
+describe('matchesAcceptToken', () => {
+  test('extension token (case-insensitive)', () => {
+    expect(matchesAcceptToken(f('photo.PNG'), '.png')).toBe(true)
+    expect(matchesAcceptToken(f('doc.pdf'), '.png')).toBe(false)
+  })
+
+  test('exact MIME token', () => {
+    expect(matchesAcceptToken(f('a', 'image/png'), 'image/png')).toBe(true)
+    expect(matchesAcceptToken(f('a', 'image/jpeg'), 'image/png')).toBe(false)
+  })
+
+  test('MIME wildcard token', () => {
+    expect(matchesAcceptToken(f('a', 'image/jpeg'), 'image/*')).toBe(true)
+    expect(matchesAcceptToken(f('a', 'video/mp4'), 'image/*')).toBe(false)
+  })
+
+  test('empty/whitespace token never matches', () => {
+    expect(matchesAcceptToken(f('a', 'image/png'), '   ')).toBe(false)
+  })
+})
+
+describe('fileMatchesAccept', () => {
+  test('absent or empty accept passes everything', () => {
+    expect(fileMatchesAccept(f('a', 'application/zip'))).toBe(true)
+    expect(fileMatchesAccept(f('a', 'application/zip'), '')).toBe(true)
+    expect(fileMatchesAccept(f('a', 'application/zip'), ' , ')).toBe(true)
+  })
+
+  test('matches when any token matches', () => {
+    expect(fileMatchesAccept(f('a.pdf', 'application/pdf'), 'image/*,.pdf')).toBe(true)
+    expect(fileMatchesAccept(f('a.png', 'image/png'), 'image/*,.pdf')).toBe(true)
+    expect(fileMatchesAccept(f('a.txt', 'text/plain'), 'image/*,.pdf')).toBe(false)
+  })
+})
+
+describe('selectFiles', () => {
+  const files = [f('a.png', 'image/png'), f('b.txt', 'text/plain'), f('c.jpg', 'image/jpeg')]
+
+  test('filters by accept', () => {
+    const out = selectFiles(files, { accept: 'image/*' })
+    expect(out.map((x) => x.name)).toEqual(['a.png', 'c.jpg'])
+  })
+
+  test('collapses to one when multiple is false', () => {
+    const out = selectFiles(files, { accept: 'image/*', multiple: false })
+    expect(out.map((x) => x.name)).toEqual(['a.png'])
+  })
+
+  test('keeps all when multiple omitted (defaults to many)', () => {
+    const out = selectFiles(files, {})
+    expect(out).toHaveLength(3)
+  })
+
+  test('empty when nothing matches', () => {
+    expect(selectFiles(files, { accept: 'video/*' })).toEqual([])
+  })
+})

package/src/react/index.ts

@@ -1,2 +1,5 @@
-export * from './upload-provider'
-export * from './use-uploader'
+export { isUploadStore, UploadProvider, useUploadStore } from './upload-provider'
+export type { Uploader } from './uploader.types'
+export type { UseDropzoneOptions, UseDropzoneReturn } from './use-dropzone'
+export { fileMatchesAccept, matchesAcceptToken, selectFiles, useDropzone } from './use-dropzone'
+export { createUploadFactory, useUploader, useUploaderActions } from './use-uploader'