@gentleduck/upload 0.2.5 → 0.3.0

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

@@ -0,0 +1,126 @@
+/**
+ * File hashing entry point.
+ *
+ * Small files use `crypto.subtle.digest` (native, fastest). Large files are
+ * hashed incrementally so memory stays flat, off the main thread via a Web
+ * Worker when the environment supports one, or inline on the current thread as
+ * a fallback (Node/SSR/tests, or browsers without Worker/Blob URL support).
+ *
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+
+import { DEFAULT_HASH_CHUNK_SIZE, sha256HexOfBlob } from './sha256'
+
+export { DEFAULT_HASH_CHUNK_SIZE, sha256HexOfBlob }
+
+/** Native Web Crypto digest of a fully-buffered blob. Lowercase hex. */
+async function sha256HexViaSubtle(blob: Blob): Promise<string> {
+  const buf = await blob.arrayBuffer()
+  const digest = await crypto.subtle.digest('SHA-256', buf)
+  const bytes = new Uint8Array(digest)
+  let out = ''
+  for (const b of bytes) out += b.toString(16).padStart(2, '0')
+  return out
+}
+
+/** True when this realm can spin up a Blob-URL Web Worker. */
+function canUseWorker(): boolean {
+  return (
+    typeof Worker !== 'undefined' &&
+    typeof Blob !== 'undefined' &&
+    typeof URL !== 'undefined' &&
+    typeof URL.createObjectURL === 'function'
+  )
+}
+
+let workerScriptUrl: string | null = null
+
+/**
+ * Build (once) an object-URL for a worker that runs {@link sha256HexOfBlob}.
+ * The function is self-contained, so stringifying it yields valid worker source.
+ */
+function getWorkerScriptUrl(): string {
+  if (workerScriptUrl) return workerScriptUrl
+  const source = `const sha256HexOfBlob = ${sha256HexOfBlob.toString()};
+self.onmessage = async (e) => {
+  try {
+    const hex = await sha256HexOfBlob(e.data.blob, { chunkSize: e.data.chunkSize });
+    self.postMessage({ ok: true, hex });
+  } catch (err) {
+    self.postMessage({ ok: false, error: String((err && err.message) || err) });
+  }
+};`
+  const blob = new Blob([source], { type: 'application/javascript' })
+  workerScriptUrl = URL.createObjectURL(blob)
+  return workerScriptUrl
+}
+
+/** Hash `blob` in a Web Worker. Rejects if the worker errors. */
+function sha256HexInWorker(blob: Blob, chunkSize: number): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    let worker: Worker
+    try {
+      worker = new Worker(getWorkerScriptUrl())
+    } catch (err) {
+      reject(err instanceof Error ? err : new Error(String(err)))
+      return
+    }
+
+    const done = (fn: () => void) => {
+      worker.onmessage = null
+      worker.onerror = null
+      worker.terminate()
+      fn()
+    }
+
+    worker.onmessage = (e: MessageEvent<{ ok: boolean; hex?: string; error?: string }>) => {
+      const data = e.data
+      if (data.ok && typeof data.hex === 'string') {
+        done(() => resolve(data.hex as string))
+      } else {
+        done(() => reject(new Error(data.error ?? 'hash worker failed')))
+      }
+    }
+    worker.onerror = (e) => {
+      done(() => reject(new Error(e.message || 'hash worker error')))
+    }
+
+    worker.postMessage({ blob, chunkSize })
+  })
+}
+
+/**
+ * Compute the lowercase hex SHA-256 of `blob`.
+ *
+ * @param blob - Source bytes.
+ * @param opts.inlineMaxSize - At or below this size, hash inline with Web Crypto
+ *   (fast, buffers the whole blob). Above it, hash incrementally — off-thread
+ *   when a Worker is available, otherwise inline-incremental. Defaults to
+ *   {@link DEFAULT_HASH_CHUNK_SIZE}.
+ * @param opts.chunkSize - Slice size for incremental hashing.
+ * @param opts.signal - Abort signal (honored on the inline-incremental path).
+ */
+export async function hashBlob(
+  blob: Blob,
+  opts?: { inlineMaxSize?: number; chunkSize?: number; signal?: AbortSignal },
+): Promise<string> {
+  const inlineMax =
+    typeof opts?.inlineMaxSize === 'number' && Number.isFinite(opts.inlineMaxSize) && opts.inlineMaxSize > 0
+      ? opts.inlineMaxSize
+      : DEFAULT_HASH_CHUNK_SIZE
+  const chunkSize = opts?.chunkSize ?? DEFAULT_HASH_CHUNK_SIZE
+
+  if (blob.size <= inlineMax && typeof crypto !== 'undefined' && crypto.subtle) {
+    return sha256HexViaSubtle(blob)
+  }
+
+  if (canUseWorker() && !opts?.signal) {
+    try {
+      return await sha256HexInWorker(blob, chunkSize)
+    } catch {
+      // Fall through to inline-incremental on any worker failure.
+    }
+  }
+
+  return opts?.signal ? sha256HexOfBlob(blob, { chunkSize, signal: opts.signal }) : sha256HexOfBlob(blob, { chunkSize })
+}

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 }
+}