@gentleduck/upload 0.2.6 → 0.3.0

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

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'vitest'
+import { isPrivateHost, validateUploadUrl } from '../url-safety'
+
+describe('isPrivateHost - IPv4', () => {
+  test('127.0.0.1 (loopback)', () => expect(isPrivateHost('127.0.0.1')).toBe(true))
+  test('10.0.0.1 (RFC1918)', () => expect(isPrivateHost('10.0.0.1')).toBe(true))
+  test('172.16.0.1 (RFC1918)', () => expect(isPrivateHost('172.16.0.1')).toBe(true))
+  test('172.31.255.255 (RFC1918 upper edge)', () => expect(isPrivateHost('172.31.255.255')).toBe(true))
+  test('172.32.0.1 (just outside RFC1918)', () => expect(isPrivateHost('172.32.0.1')).toBe(false))
+  test('192.168.1.1 (RFC1918)', () => expect(isPrivateHost('192.168.1.1')).toBe(true))
+  test('169.254.169.254 (AWS metadata)', () => expect(isPrivateHost('169.254.169.254')).toBe(true))
+  test('0.0.0.0 (this-network)', () => expect(isPrivateHost('0.0.0.0')).toBe(true))
+  test('100.64.0.1 (CGNAT)', () => expect(isPrivateHost('100.64.0.1')).toBe(true))
+  test('224.0.0.1 (multicast)', () => expect(isPrivateHost('224.0.0.1')).toBe(true))
+  test('255.255.255.255 (broadcast)', () => expect(isPrivateHost('255.255.255.255')).toBe(true))
+  test('8.8.8.8 (public)', () => expect(isPrivateHost('8.8.8.8')).toBe(false))
+  test('octet > 255 (malformed)', () => expect(isPrivateHost('256.0.0.0')).toBe(false))
+})
+
+describe('isPrivateHost - IPv6', () => {
+  test('::1 (loopback)', () => expect(isPrivateHost('::1')).toBe(true))
+  test('[::1] bracketed', () => expect(isPrivateHost('[::1]')).toBe(true))
+  test(':: (unspecified)', () => expect(isPrivateHost('::')).toBe(true))
+  test('fc00::1 (ULA)', () => expect(isPrivateHost('fc00::1')).toBe(true))
+  test('fe80::1 (link-local)', () => expect(isPrivateHost('fe80::1')).toBe(true))
+  test('ff00::1 (multicast)', () => expect(isPrivateHost('ff00::1')).toBe(true))
+  test('2001:db8::1 (documentation)', () => expect(isPrivateHost('2001:db8::1')).toBe(false))
+})
+
+describe('isPrivateHost - IPv6 embedded IPv4', () => {
+  test('::ffff:127.0.0.1 (IPv4-mapped, dotted-quad tail)', () => {
+    expect(isPrivateHost('::ffff:127.0.0.1')).toBe(true)
+  })
+  test('::ffff:7f00:1 (IPv4-mapped, hex tail)', () => {
+    expect(isPrivateHost('::ffff:7f00:1')).toBe(true)
+  })
+  test('::127.0.0.1 (IPv4-compat)', () => expect(isPrivateHost('::127.0.0.1')).toBe(true))
+  test('2002:7f00:1:: (6to4 carrying loopback)', () => expect(isPrivateHost('2002:7f00:1::')).toBe(true))
+  test('64:ff9b::127.0.0.1 (NAT64 carrying loopback)', () => {
+    expect(isPrivateHost('64:ff9b::127.0.0.1')).toBe(true)
+  })
+})
+
+describe('isPrivateHost - hostnames are NOT IP literals', () => {
+  test('example.com (FQDN)', () => expect(isPrivateHost('example.com')).toBe(false))
+  test('localhost (resolves to loopback at runtime; not literal)', () => {
+    expect(isPrivateHost('localhost')).toBe(false)
+  })
+})
+
+describe('validateUploadUrl - rejected inputs', () => {
+  test('empty', () => expect(() => validateUploadUrl('', 'test')).toThrow(/empty or non-string/))
+  test('non-string', () => expect(() => validateUploadUrl(null as unknown as string, 'test')).toThrow())
+  test('path traversal', () => expect(() => validateUploadUrl('https://x.com/../etc', 'test')).toThrow(/forbidden/))
+  test('malformed', () => expect(() => validateUploadUrl('not a url', 'test')).toThrow(/malformed/))
+  test('file://', () => expect(() => validateUploadUrl('file:///etc/passwd', 'test')).toThrow(/forbidden protocol/))
+  test('javascript:', () =>
+    expect(() => validateUploadUrl('javascript:alert(1)', 'test')).toThrow(/forbidden protocol/))
+  test('data:', () => expect(() => validateUploadUrl('data:text/html,evil', 'test')).toThrow(/forbidden protocol/))
+  test('private host', () => expect(() => validateUploadUrl('https://127.0.0.1/x', 'test')).toThrow(/private/))
+  test('AWS metadata', () =>
+    expect(() => validateUploadUrl('https://169.254.169.254/latest/meta-data/', 'test')).toThrow(/private/))
+})
+
+describe('validateUploadUrl - allowedHosts', () => {
+  test('host in allowlist passes', () => {
+    expect(() =>
+      validateUploadUrl('https://up.example.com/x', 'test', { allowedHosts: ['up.example.com'] }),
+    ).not.toThrow()
+  })
+  test('host outside allowlist rejected', () => {
+    expect(() => validateUploadUrl('https://evil.example.com/x', 'test', { allowedHosts: ['up.example.com'] })).toThrow(
+      /allow-list/,
+    )
+  })
+  test('case-insensitive match', () => {
+    expect(() =>
+      validateUploadUrl('https://UP.Example.COM/x', 'test', { allowedHosts: ['up.example.com'] }),
+    ).not.toThrow()
+  })
+  test('host with port matches list with port', () => {
+    expect(() =>
+      validateUploadUrl('https://up.example.com:8443/x', 'test', { allowedHosts: ['up.example.com:8443'] }),
+    ).not.toThrow()
+  })
+})
+
+describe('validateUploadUrl - length cap', () => {
+  test('rejects URL > 8192 bytes', () => {
+    const huge = `https://x.com/${'a'.repeat(9000)}`
+    expect(() => validateUploadUrl(huge, 'test')).toThrow(/exceeds 8192-byte/)
+  })
+  test('accepts URL at the 8192 boundary', () => {
+    const base = 'https://x.example.com/'
+    const padded = base + 'a'.repeat(8192 - base.length)
+    expect(padded.length).toBe(8192)
+    expect(() => validateUploadUrl(padded, 'test')).not.toThrow()
+  })
+})
+
+describe('validateUploadUrl - allowPrivateHosts opt-in', () => {
+  test('127.0.0.1 passes when allowPrivateHosts true', () => {
+    expect(() => validateUploadUrl('https://127.0.0.1/x', 'test', { allowPrivateHosts: true })).not.toThrow()
+  })
+})
+
+describe('validateUploadUrl - caller label in error messages', () => {
+  test('throws include the caller label', () => {
+    expect(() => validateUploadUrl('file:///x', 'multipart.signPart')).toThrow(/multipart\.signPart/)
+    expect(() => validateUploadUrl('https://127.0.0.1/x', 'post.intent')).toThrow(/post\.intent/)
+  })
+})

package/src/core/utils/async.ts

@@ -1,3 +1,8 @@
-export function sleep(ms: number) {
-  return new Promise<void>((resolve) => setTimeout(resolve, ms))
+/**
+ * Awaitable timer. Clamps `ms` to `[0, 86_400_000]` (24h) so a NaN /
+ * Infinity / negative argument can't wedge the scheduler.
+ */
+export function sleep(ms: number): Promise<void> {
+  const clamped = Number.isFinite(ms) && ms > 0 ? Math.min(ms, 86_400_000) : 0
+  return new Promise<void>((resolve) => setTimeout(resolve, clamped))
 }

package/src/core/utils/constants.ts

@@ -16,17 +16,11 @@ export const DEFAULT_RETRY_DELAY_MAX_MS = 10_000
  */
 export const DEFAULT_PROGRESS_THROTTLE_MS = 100
 
-/**
- * Default maximum number of retry attempts.
- */
+/** Default maximum number of retry attempts. */
 export const DEFAULT_MAX_ATTEMPTS = 3
 
-/**
- * Default maximum number of concurrent uploads.
- */
+/** Default maximum number of concurrent uploads. */
 export const DEFAULT_MAX_CONCURRENT_UPLOADS = 3
 
-/**
- * Default maximum number of items to keep in memory.
- */
+/** Default maximum number of items to keep in memory. */
 export const DEFAULT_MAX_ITEMS = 100

package/src/core/utils/emitter/emitter.ts

@@ -1,23 +1,6 @@
+import { isDevEnv } from '../guards'
 import type { Emitter } from './emitter.types'
 
-/**
- * Listener-throw callback. Re-exported alias for the canonical
- * {@link Emitter.ErrorHandler} type. Kept for backwards compatibility
- * with R30 import paths; prefer `Emitter.ErrorHandler` in new code.
- *
- * @author wildduck2 <https://github.com/wildduck2>
- */
-export type EmitterErrorHandler = Emitter.ErrorHandler
-
-/**
- * Listener registry, bucketed by event type.
- *
- * @template E Event map.
- */
-type ListenerMap<E extends Record<string, unknown>> = Partial<{
-  [K in keyof E & string]: Set<(payload: E[K]) => void>
-}>
-
 /**
  * Soft cap on nested `emit` depth. A listener that synchronously dispatches a
  * command which fires another emit is legal -- but unbounded re-entry usually
@@ -44,9 +27,9 @@ const MAX_EMIT_DEPTH = 50
  * @author wildduck2 <https://github.com/wildduck2>
  */
 export function createTypedEmitter<E extends Record<string, unknown>>(
-  onError?: EmitterErrorHandler,
-): Emitter.ITypedEmitter<E> {
-  const listeners: ListenerMap<E> = {}
+  onError?: Emitter.ErrorHandler,
+): Emitter.TypedEmitter<E> {
+  const listeners: Emitter.ListenerMap<E> = {}
   // Memoized iteration snapshots per event type. Invalidated on `on`/`off`.
   // Multi-listener `emit` would otherwise allocate a fresh array every call;
   // for progress streams that adds up to one Set + spread per progress tick.
@@ -99,7 +82,7 @@ export function createTypedEmitter<E extends Record<string, unknown>>(
             } catch {}
             return
           }
-          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+          if (isDevEnv()) {
             console.error(`[UploadEngine] Error in event listener for "${type}":`, err)
           }
         }
@@ -107,7 +90,7 @@ export function createTypedEmitter<E extends Record<string, unknown>>(
 
       emitDepth++
       try {
-        if (emitDepth > MAX_EMIT_DEPTH && !warnedDepth && process.env.NODE_ENV !== 'production') {
+        if (emitDepth > MAX_EMIT_DEPTH && !warnedDepth && isDevEnv()) {
           warnedDepth = true
           console.warn(
             `[UploadEngine] emit depth exceeded ${MAX_EMIT_DEPTH} for "${type}". ` +
@@ -121,7 +104,7 @@ export function createTypedEmitter<E extends Record<string, unknown>>(
         // most subscribers attach exactly one listener per event type.
         if (typeListeners.size === 1) {
           const [only] = typeListeners
-          dispatch(only)
+          if (only) dispatch(only)
           return
         }
 

package/src/core/utils/emitter/emitter.types.ts

@@ -1,23 +1,40 @@
-/**
- * Minimal typed event emitter interface.
- *
- * Use this to expose strongly-typed events from your store.
- *
- * @typeParam E - Event map (`eventName -> payload`).
- */
-export type TypedEmitter<E extends Record<string, unknown>> = {
+export namespace Emitter {
   /**
-   * Subscribe to an event.
-   * @returns Unsubscribe function.
+   * Minimal typed event emitter interface.
+   *
+   * Use this to expose strongly-typed events from your store.
+   *
+   * @typeParam E - Event map (`eventName -> payload`).
    */
-  on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void
+  export type TypedEmitter<E extends Record<string, unknown>> = {
+    /**
+     * Subscribe to an event.
+     * @returns Unsubscribe function.
+     */
+    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void
+
+    /**
+     * Unsubscribe from an event.
+     */
+    off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): void
+
+    /** Emit an event to all listeners. */
+    emit<K extends keyof E & string>(type: K, payload: E[K]): void
+  }
 
   /**
-   * Unsubscribe from an event.
-   * @returns Unsubscribe function.
+   * Callback invoked when a listener throws during `emit`, so one bad listener
+   * cannot break the dispatch loop. Receives the event type, the thrown error,
+   * and the listener that threw.
    */
-  off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void
+  export type ErrorHandler = (type: string, error: unknown, cb: (...args: any[]) => void) => void
 
-  /** Emit an event to all listeners. */
-  emit<K extends keyof E & string>(type: K, payload: E[K]): void
+  /**
+   * Listener registry, bucketed by event type.
+   *
+   * @template E Event map.
+   */
+  export type ListenerMap<E extends Record<string, unknown>> = Partial<{
+    [K in keyof E & string]: Set<(payload: E[K]) => void>
+  }>
 }

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

@@ -1,74 +1,2 @@
-import type { TypedEmitter } from './emitter.types'
-
-export type { TypedEmitter } from './emitter.types'
-
-/**
- * Creates a lightweight, typed event emitter.
- * We use this instead of `EventEmitter` or `EventTarget` to ensure:
- * 1. Strict typing of event payloads (via generic E)
- * 2. No dependency on Node.js built-ins (browser compatible)
- * 3. Exception safety (user listeners don't crash the loop)
- *
- * @template E - Event map type (Record<eventName, payloadType>)
- *
- * @returns {TypedEmitter<E>} Typed emitter instance
- *
- * @example
- * ```ts
- * type Events = { 'file.added': { id: string }, 'upload.progress': { pct: number } }
- * const emitter = createTypedEmitter<Events>()
- * emitter.on('file.added', (payload) => console.log(payload.id))
- * ```
- */
-type ListenerMap<E extends Record<string, unknown>> = Partial<{
-  [K in keyof E & string]: Set<(payload: E[K]) => void>
-}>
-
-export function createTypedEmitter<E extends Record<string, unknown>>(): TypedEmitter<E> {
-  const listeners: ListenerMap<E> = {}
-
-  return {
-    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
-      // Create listener set for this event type if it doesn't exist
-      let set = listeners[type]
-      if (!set) {
-        set = new Set<(payload: E[K]) => void>()
-        listeners[type] = set
-      }
-      set.add(cb)
-
-      // Return unsubscribe function
-      return () => {
-        const typeListeners = listeners[type]
-        if (!typeListeners) return
-        typeListeners.delete(cb)
-        if (typeListeners.size === 0) delete listeners[type]
-      }
-    },
-
-    off<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
-      const typeListeners = listeners[type]
-      if (!typeListeners) return () => {}
-      typeListeners.delete(cb)
-      if (typeListeners.size === 0) delete listeners[type]
-      return () => {}
-    },
-
-    emit<K extends keyof E & string>(type: K, payload: E[K]): void {
-      const typeListeners = listeners[type]
-      if (!typeListeners) return
-
-      typeListeners.forEach((cb) => {
-        try {
-          cb(payload)
-        } catch (err) {
-          // Do not crash upload engine due to user callbacks
-          // In production, this should be sent to error tracking service
-          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
-            console.error(`[UploadEngine] Error in event listener for "${type}":`, err)
-          }
-        }
-      })
-    },
-  }
-}
+export { createTypedEmitter } from './emitter'
+export type { Emitter } from './emitter.types'

package/src/core/utils/fingerprint.ts

@@ -1,20 +1,31 @@
-import type { FileFingerprint } from '../contracts'
+import type { Contracts } from '../contracts'
 
 /**
  * Builds a lightweight fingerprint from a {@link File}.
+ *
+ * MIME is normalized: parameters after `;` are stripped (Bun's File
+ * constructor appends `;charset=utf-8` to text/* types; browsers send
+ * the bare MIME via FormData). Persisted fingerprints stay portable
+ * across runtimes.
  */
-export function computeFingerprint(file: File): FileFingerprint {
+export function computeFingerprint(file: File): Contracts.FingerprintFile {
   return {
     name: file.name,
     size: file.size,
-    type: file.type,
+    type: normalizeMime(file.type),
     lastModified: file.lastModified,
   }
 }
 
+function normalizeMime(mime: string): string {
+  const semi = mime.indexOf(';')
+  return semi === -1 ? mime.trim() : mime.slice(0, semi).trim()
+}
+
 /**
- * Compares two file fingerprints.
+ * `type` is intentionally NOT compared: a re-picked file with the same
+ * bytes but a different runtime-inferred MIME is still the same file.
  */
-export function fingerprintMatches(a: FileFingerprint, b: FileFingerprint): boolean {
+export function fingerprintMatches(a: Contracts.FingerprintFile, b: Contracts.FingerprintFile): boolean {
   return a.name === b.name && a.size === b.size && a.lastModified === b.lastModified
 }

package/src/core/utils/guards.ts

@@ -1,3 +1,93 @@
+/**
+ * Maximum recursion depth for {@link stripDangerousKeys}. Values nested deeper
+ * are left as-is, guarding against pathological or cyclic persistence payloads
+ * without aborting hydration.
+ */
+const MAX_STRIP_DEPTH = 16
+
+const DANGEROUS_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * Narrow guard for plain records (object literal or `Object.create(null)`).
+ * Rejects arrays, `Date`, `Map`, `Set`, and class instances — only
+ * `null`-prototype or `Object.prototype` objects pass. Keeps arrays and class
+ * instances out of runtime state during snapshot hydration.
+ */
 export function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object'
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === null || proto === Object.prototype
+}
+
+/**
+ * Safe `NODE_ENV === 'development'` check for dev-only diagnostics (console
+ * warnings/errors that must never affect control flow).
+ *
+ * Bundlers that replace `process.env.NODE_ENV` (Vite, esbuild, webpack's
+ * DefinePlugin) only match that exact dotted-property expression - a bare
+ * `process` reference is never actually defined in the shipped browser
+ * bundle. Reading `process.env['NODE_ENV']` (or any other form the bundler
+ * doesn't statically match) throws `ReferenceError: process is not defined`
+ * at runtime instead of the constant-folded string, turning a should-be-inert
+ * dev warning into a hard crash. Guarding with `typeof process !== 'undefined'`
+ * avoids ever touching the global unless something has actually defined it.
+ */
+export function isDevEnv(): boolean {
+  return typeof window !== 'undefined' && typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development'
+}
+
+/**
+ * Recursively strip `__proto__`, `constructor`, and `prototype` keys from a
+ * parsed value tree before it is spread into runtime state. Arrays are
+ * traversed; exotic objects (Date, Map, class instances) are returned
+ * untouched. Uses an explicit work stack so deeply nested payloads cannot
+ * overflow the call stack, and stops at {@link MAX_STRIP_DEPTH} to stay cycle-
+ * and depth-safe.
+ */
+export function stripDangerousKeys<T>(input: T): T {
+  if (input === null || typeof input !== 'object') return input
+
+  type Frame = { value: object; depth: number }
+  const stack: Frame[] = [{ value: input as unknown as object, depth: 0 }]
+  const seen = new WeakSet<object>()
+
+  while (stack.length > 0) {
+    const frame = stack.pop()
+    if (!frame) break
+
+    const { value, depth } = frame
+    if (seen.has(value)) continue
+    seen.add(value)
+
+    if (depth >= MAX_STRIP_DEPTH) continue
+
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child !== null && typeof child === 'object') {
+          stack.push({ value: child, depth: depth + 1 })
+        }
+      }
+      continue
+    }
+
+    const proto = Object.getPrototypeOf(value)
+    if (proto !== null && proto !== Object.prototype) {
+      // Exotic object (Date, Map, class instance) — leave untouched.
+      continue
+    }
+
+    const obj = value as Record<string, unknown>
+    for (const key of Object.keys(obj)) {
+      if (DANGEROUS_KEYS.has(key)) {
+        delete obj[key]
+        continue
+      }
+      const child = obj[key]
+      if (child !== null && typeof child === 'object') {
+        stack.push({ value: child, depth: depth + 1 })
+      }
+    }
+  }
+
+  return input
 }

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { hashBlob, sha256HexOfBlob } from '../index'
+
+/** Reference digest via native Web Crypto. */
+async function subtleHex(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', bytes as unknown as BufferSource)
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+describe('sha256HexOfBlob', () => {
+  it('matches known vectors', async () => {
+    // FIPS 180-2 vectors.
+    expect(await sha256HexOfBlob(new Blob([]))).toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')
+    expect(await sha256HexOfBlob(new Blob(['abc']))).toBe(
+      'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad',
+    )
+    expect(await sha256HexOfBlob(new Blob(['abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq']))).toBe(
+      '248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1',
+    )
+  })
+
+  it('is chunk-size invariant', async () => {
+    const bytes = new Uint8Array(4096)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 131 + 7) & 0xff
+    const blob = new Blob([bytes])
+    const expected = await subtleHex(bytes)
+    for (const chunkSize of [1, 3, 55, 63, 64, 65, 128, 1000, 4096, 8192]) {
+      expect(await sha256HexOfBlob(blob, { chunkSize })).toBe(expected)
+    }
+  })
+
+  it('hashes across the 55/56/64-byte padding boundaries', async () => {
+    for (const n of [0, 1, 55, 56, 57, 63, 64, 65, 119, 120, 128]) {
+      const bytes = new Uint8Array(n)
+      for (let i = 0; i < n; i++) bytes[i] = (i * 17) & 0xff
+      expect(await sha256HexOfBlob(new Blob([bytes]), { chunkSize: 7 })).toBe(await subtleHex(bytes))
+    }
+  })
+
+  it('aborts between slices', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    await expect(
+      sha256HexOfBlob(new Blob([new Uint8Array(1000)]), { chunkSize: 10, signal: controller.signal }),
+    ).rejects.toThrow(/abort/i)
+  })
+})
+
+describe('hashBlob', () => {
+  it('inline and incremental paths agree', async () => {
+    const bytes = new Uint8Array(2048)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 7 + 3) & 0xff
+    const blob = new Blob([bytes])
+    const inline = await hashBlob(blob, { inlineMaxSize: 4096 }) // <= boundary -> subtle
+    const incremental = await hashBlob(blob, { inlineMaxSize: 16, chunkSize: 100 }) // > boundary -> incremental
+    expect(inline).toBe(incremental)
+    expect(inline).toBe(await subtleHex(bytes))
+  })
+})

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