@gentleduck/upload 0.2.5 → 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

@@ -0,0 +1,126 @@
+import { isDevEnv } from '../guards'
+import type { Emitter } from './emitter.types'
+
+/**
+ * Soft cap on nested `emit` depth. A listener that synchronously dispatches a
+ * command which fires another emit is legal -- but unbounded re-entry usually
+ * means a feedback loop. The cap surfaces it in dev without aborting.
+ */
+const MAX_EMIT_DEPTH = 50
+
+/**
+ * Build a typed event emitter with listener-throw isolation.
+ *
+ * Listeners added or removed during an `emit` see a stable snapshot of the
+ * listener set; the mutation lands on the *next* emission.
+ *
+ * @param onError Optional error sink. Receives `(type, error, listener)` on
+ *   every listener throw. Falls back to dev-only `console.error` when omitted.
+ * @returns Configured emitter exposing `on` / `off` / `emit`.
+ * @template E Event map (`Record<eventName, payloadType>`).
+ * @example
+ * ```ts
+ * type Events = { 'file.added': { id: string }, 'upload.progress': { pct: number } }
+ * const emitter = createTypedEmitter<Events>()
+ * emitter.on('file.added', (p) => console.log(p.id))
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createTypedEmitter<E extends Record<string, unknown>>(
+  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.
+  const snapshots = new Map<string, ReadonlyArray<(payload: unknown) => void>>()
+  let emitDepth = 0
+  let warnedDepth = false
+
+  const invalidate = (type: string) => {
+    if (snapshots.size > 0) snapshots.delete(type)
+  }
+
+  return {
+    on<K extends keyof E & string>(type: K, cb: (payload: E[K]) => void): () => void {
+      let set = listeners[type]
+      if (!set) {
+        set = new Set<(payload: E[K]) => void>()
+        listeners[type] = set
+      }
+      set.add(cb)
+      invalidate(type)
+
+      return () => {
+        const typeListeners = listeners[type]
+        if (!typeListeners) return
+        typeListeners.delete(cb)
+        invalidate(type)
+        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)
+      invalidate(type)
+      if (typeListeners.size === 0) delete listeners[type]
+    },
+
+    emit<K extends keyof E & string>(type: K, payload: E[K]): void {
+      const typeListeners = listeners[type]
+      if (!typeListeners || typeListeners.size === 0) return
+
+      const dispatch = (cb: (payload: E[K]) => void) => {
+        try {
+          cb(payload)
+        } catch (err) {
+          if (onError) {
+            try {
+              onError(type, err, cb as (...args: unknown[]) => void)
+            } catch {}
+            return
+          }
+          if (isDevEnv()) {
+            console.error(`[UploadEngine] Error in event listener for "${type}":`, err)
+          }
+        }
+      }
+
+      emitDepth++
+      try {
+        if (emitDepth > MAX_EMIT_DEPTH && !warnedDepth && isDevEnv()) {
+          warnedDepth = true
+          console.warn(
+            `[UploadEngine] emit depth exceeded ${MAX_EMIT_DEPTH} for "${type}". ` +
+              'A listener is likely dispatching a command that re-emits, forming a feedback loop. ' +
+              'Defer the dispatch with `queueMicrotask` to break the chain.',
+          )
+        }
+
+        // Size-1 fast path: skip the snapshot allocation when only one
+        // listener is attached. Hot path under busy progress streams where
+        // most subscribers attach exactly one listener per event type.
+        if (typeListeners.size === 1) {
+          const [only] = typeListeners
+          if (only) dispatch(only)
+          return
+        }
+
+        // Multi-listener path: reuse the memoized snapshot so `on()`/`off()`
+        // from inside a listener doesn't reshape iteration mid-flight AND
+        // back-to-back emits don't re-allocate the array.
+        let snapshot = snapshots.get(type) as ReadonlyArray<(payload: E[K]) => void> | undefined
+        if (!snapshot) {
+          snapshot = Array.from(typeListeners) as ReadonlyArray<(payload: E[K]) => void>
+          snapshots.set(type, snapshot as ReadonlyArray<(payload: unknown) => void>)
+        }
+        for (const cb of snapshot) dispatch(cb)
+      } finally {
+        emitDepth--
+        if (emitDepth === 0) warnedDepth = false
+      }
+    },
+  }
+}

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