@gentleduck/upload 0.2.5 → 0.3.0

package/src/__tests__/persistence.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from 'vitest'
+import type { Engine } from '../core/engine/engine.types'
+import { createMemoryAdapter, MemoryAdapter } from '../core/persistence'
+import { deserializeSnapshot, serializeSnapshot } from '../core/persistence/persistence'
+import type { UploadPersistence } from '../core/persistence/persistence.types'
+
+type Intents = { post: { strategy: 'post'; fileId: string; url: string } }
+type Cursors = { post: { offset: number } }
+type Purpose = 'avatar'
+type Result = { fileId: string; key: string }
+
+const isPurpose = (v: string): v is Purpose => v === 'avatar'
+const isIntent = (v: unknown): v is Intents[keyof Intents] => {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { strategy?: unknown }).strategy === 'post' &&
+    typeof (v as { fileId?: unknown }).fileId === 'string'
+  )
+}
+const hasStrategy = (s: string) => s === 'post'
+
+describe('serializeSnapshot', () => {
+  test('skips items without intents and terminal states', () => {
+    const state: Engine.State<Intents, Cursors, Purpose, Result> = {
+      items: new Map([
+        [
+          'a',
+          {
+            phase: 'validating',
+            localId: 'a',
+            purpose: 'avatar',
+            fingerprint: { name: 'a', size: 1, type: 't', lastModified: 0 },
+            file: new File(['a'], 'a'),
+            createdAt: 0,
+            steps: [],
+            meta: {},
+          },
+        ],
+        [
+          'b',
+          {
+            phase: 'completed',
+            localId: 'b',
+            purpose: 'avatar',
+            fingerprint: { name: 'b', size: 1, type: 't', lastModified: 0 },
+            file: new File(['b'], 'b'),
+            intent: { strategy: 'post', fileId: 'b', url: 'x' },
+            completedBy: 'upload',
+            result: { fileId: 'b', key: 'k/b' },
+            completedAt: 0,
+            createdAt: 0,
+            steps: [],
+            meta: {},
+          },
+        ],
+        [
+          'c',
+          {
+            phase: 'uploading',
+            localId: 'c',
+            purpose: 'avatar',
+            fingerprint: { name: 'c', size: 10, type: 't', lastModified: 0 },
+            file: new File(['c'], 'c'),
+            intent: { strategy: 'post', fileId: 'c', url: 'x' },
+            startedAt: 0,
+            progress: { uploadedBytes: 5, totalBytes: 10, pct: 50 },
+            createdAt: 0,
+            cursor: { strategy: 'post', value: { offset: 5 } },
+            steps: [],
+            meta: {},
+          },
+        ],
+      ]),
+    }
+
+    const snap = serializeSnapshot(state, 1)
+    expect(Object.keys(snap.items)).toEqual(['c'])
+    expect(snap.version).toBe(1)
+  })
+})
+
+describe('deserializeSnapshot', () => {
+  test('restores resumable items into the paused phase', () => {
+    const snap: UploadPersistence.Snapshot<Intents, Cursors, Purpose> = {
+      version: 1,
+      createdAt: 100,
+      items: {
+        c: {
+          id: 'c',
+          purpose: 'avatar',
+          status: 'uploading',
+          file: { name: 'c', size: 10, type: 't', lastModified: 0 },
+          intent: { strategy: 'post', fileId: 'c', url: 'x' },
+          cursor: { strategy: 'post', value: { offset: 5 } },
+          progress: { uploadedBytes: 5, totalBytes: 10, pct: 50 },
+        },
+      },
+    }
+
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out).not.toBeNull()
+    const item = out?.items.get('c')
+    expect(item?.phase).toBe('paused')
+    if (item?.phase === 'paused') {
+      expect(item.cursor).toEqual({ strategy: 'post', value: { offset: 5 } })
+      expect(item.progress.pct).toBe(50)
+    }
+  })
+
+  test('drops items missing a cursor', () => {
+    const snap: UploadPersistence.Snapshot<Intents, Cursors, Purpose> = {
+      version: 1,
+      createdAt: 100,
+      items: {
+        c: {
+          id: 'c',
+          purpose: 'avatar',
+          status: 'uploading',
+          file: { name: 'c', size: 10, type: 't', lastModified: 0 },
+          intent: { strategy: 'post', fileId: 'c', url: 'x' },
+        },
+      },
+    }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out?.items.size).toBe(0)
+  })
+
+  test('returns null without guards', () => {
+    const snap: UploadPersistence.Snapshot<Intents, Cursors, Purpose> = { version: 1, createdAt: 0, items: {} }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, { hasStrategy })
+    expect(out).toBeNull()
+  })
+
+  test('accepts snapshots and ignores unrecognized version when not enforced', () => {
+    const snap: UploadPersistence.Snapshot<Intents, Cursors, Purpose> = { version: 1, createdAt: 0, items: {} }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out).not.toBeNull()
+    expect(out?.items.size).toBe(0)
+  })
+})
+
+describe('MemoryAdapter', () => {
+  test('round-trips a value', async () => {
+    await MemoryAdapter.save('k', { a: 1 })
+    expect(await MemoryAdapter.load('k')).toEqual({ a: 1 })
+    await MemoryAdapter.clear('k')
+    expect(await MemoryAdapter.load('k')).toBeNull()
+  })
+})
+
+describe('createMemoryAdapter factory isolation', () => {
+  test('two factory calls produce isolated state', async () => {
+    const a = createMemoryAdapter()
+    const b = createMemoryAdapter()
+    await a.save('key', { from: 'a' })
+    expect(await b.load('key')).toBeNull()
+    await b.save('key', { from: 'b' })
+    expect(await a.load('key')).toEqual({ from: 'a' })
+    expect(await b.load('key')).toEqual({ from: 'b' })
+  })
+
+  test('clear on one adapter does not affect another', async () => {
+    const a = createMemoryAdapter()
+    const b = createMemoryAdapter()
+    await a.save('shared', 1)
+    await b.save('shared', 2)
+    await a.clear('shared')
+    expect(await a.load('shared')).toBeNull()
+    expect(await b.load('shared')).toBe(2)
+  })
+
+  test('backwards-compat singleton still round-trips', async () => {
+    await MemoryAdapter.save('compat', { v: 1 })
+    expect(await MemoryAdapter.load('compat')).toEqual({ v: 1 })
+    await MemoryAdapter.clear('compat')
+    expect(await MemoryAdapter.load('compat')).toBeNull()
+  })
+})

package/src/__tests__/sanitize-filename.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from 'vitest'
+import { sanitizeFilename } from '../core/utils/sanitize-filename'
+
+describe('sanitizeFilename', () => {
+  test('happy path: ordinary name passes through unchanged', () => {
+    const r = sanitizeFilename('report-2026.pdf')
+    expect(r).toEqual({ safe: true, normalised: 'report-2026.pdf' })
+  })
+
+  test('CON.txt rejected as reserved (Windows device name)', () => {
+    const r = sanitizeFilename('CON.txt')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('reserved')
+  })
+
+  test('lowercase nul rejected as reserved (case-insensitive)', () => {
+    const r = sanitizeFilename('nul')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('reserved')
+  })
+
+  test('COM1.tar.gz rejected (reserved base, ignoring extension)', () => {
+    const r = sanitizeFilename('COM1.tar.gz')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('reserved')
+  })
+
+  test('-rm-rf.txt → leading dash stripped, becomes rm-rf.txt', () => {
+    const r = sanitizeFilename('-rm-rf.txt')
+    expect(r).toEqual({ safe: true, normalised: 'rm-rf.txt' })
+  })
+
+  test('multiple leading dashes all stripped', () => {
+    const r = sanitizeFilename('---flag.bin')
+    expect(r).toEqual({ safe: true, normalised: 'flag.bin' })
+  })
+
+  test('trailing dots and spaces stripped (Windows behaviour)', () => {
+    expect(sanitizeFilename('file.txt.').normalised).toBe('file.txt')
+    expect(sanitizeFilename('file.txt ').normalised).toBe('file.txt')
+    expect(sanitizeFilename('file.txt. . .').normalised).toBe('file.txt')
+  })
+
+  test('RTL override and other compat chars get NFKC normalised', () => {
+    // U+202E RIGHT-TO-LEFT OVERRIDE  stripped via NFKC?
+    // NFKC does not strip RLO, but the test confirms normalize() is applied;
+    // we focus on the fullwidth → ASCII collapse which is the typical bypass.
+    const fullwidth = 'ｆｕｌｌ.pdf' // "ｆｕｌｌ.pdf" → "full.pdf"
+    const r = sanitizeFilename(fullwidth)
+    expect(r).toEqual({ safe: true, normalised: 'full.pdf' })
+  })
+
+  test('control chars cleaned (NUL byte)', () => {
+    const r = sanitizeFilename('file\x00name.txt')
+    expect(r).toEqual({ safe: true, normalised: 'filename.txt' })
+  })
+
+  test('control chars cleaned (CR/LF  header smuggling)', () => {
+    const r = sanitizeFilename('a\r\nb.txt')
+    expect(r).toEqual({ safe: true, normalised: 'ab.txt' })
+  })
+
+  test('DEL (0x7F) is stripped', () => {
+    const r = sanitizeFilename('a\x7Fb.txt')
+    expect(r).toEqual({ safe: true, normalised: 'ab.txt' })
+  })
+
+  test('300-char name rejected as too-long', () => {
+    const r = sanitizeFilename('a'.repeat(300) + '.txt')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('too-long')
+  })
+
+  test('exactly 255 chars passes', () => {
+    const name = 'a'.repeat(251) + '.txt' // 255 total
+    const r = sanitizeFilename(name)
+    expect(r.safe).toBe(true)
+  })
+
+  test('forward slash path separator rejected', () => {
+    const r = sanitizeFilename('foo/bar.txt')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('path-sep')
+  })
+
+  test('backslash path separator rejected', () => {
+    const r = sanitizeFilename('foo\\bar.txt')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('path-sep')
+  })
+
+  test('empty input rejected', () => {
+    const r = sanitizeFilename('')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('empty')
+  })
+
+  test('name that vanishes after sanitisation rejected as empty', () => {
+    const r = sanitizeFilename('---. . .')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('empty')
+  })
+
+  test('control-only input rejected as empty', () => {
+    const r = sanitizeFilename('\x00\x01\x02')
+    expect(r.safe).toBe(false)
+    expect(r.safe === false && r.reason).toBe('empty')
+  })
+})

package/src/__tests__/sleep.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'vitest'
+import { sleep } from '../core/utils/async'
+
+describe('sleep - clamps adversarial inputs', () => {
+  test('NaN resolves immediately', async () => {
+    const t0 = Date.now()
+    await sleep(Number.NaN)
+    expect(Date.now() - t0).toBeLessThan(50)
+  })
+
+  test('Infinity resolves within the 24h cap (but we only wait briefly to confirm it scheduled)', async () => {
+    // Can't actually wait 24h; assert that the call doesn't throw / hang the test.
+    const p = sleep(Number.POSITIVE_INFINITY)
+    expect(p).toBeInstanceOf(Promise)
+  })
+
+  test('negative ms resolves immediately', async () => {
+    const t0 = Date.now()
+    await sleep(-1000)
+    expect(Date.now() - t0).toBeLessThan(50)
+  })
+
+  test('zero ms resolves immediately', async () => {
+    const t0 = Date.now()
+    await sleep(0)
+    expect(Date.now() - t0).toBeLessThan(50)
+  })
+
+  test('finite positive ms waits at least that long', async () => {
+    const t0 = Date.now()
+    await sleep(20)
+    expect(Date.now() - t0).toBeGreaterThanOrEqual(15)
+  })
+})

package/src/__tests__/static-analysis.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Static-analysis assertions that enforce security invariants by
+ * grepping the source tree at test time.
+ *
+ * These guard the class of bug that survives a refactor + the existing
+ * happy-path tests: someone replaces `crypto.randomUUID` with
+ * `Math.random()`, or removes the SSRF guard from a strategy, and the
+ * existing tests still pass because they don't cover the regression
+ * lane. If one of these tests fails, fix the source - do not allowlist
+ * without understanding which threat the rule was protecting against.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+interface FileScan {
+  path: string
+  contents: string
+}
+
+function walkTs(dir: string, out: FileScan[] = []): FileScan[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === 'dist' || entry.startsWith('__test')) continue
+    const full = join(dir, entry)
+    const stat = statSync(full)
+    if (stat.isDirectory()) {
+      walkTs(full, out)
+    } else if (entry.endsWith('.ts') || entry.endsWith('.tsx')) {
+      out.push({ path: full.slice(ROOT.length + 1), contents: readFileSync(full, 'utf8') })
+    }
+  }
+  return out
+}
+
+const ALL_FILES = walkTs(ROOT)
+
+const SECURITY_PATHS = ['core/utils/', 'core/engine/', 'core/persistence/', 'core/contracts/', 'strategies/']
+
+function isSecurityPath(path: string): boolean {
+  return SECURITY_PATHS.some((p) => path.includes(p))
+}
+
+function linesContaining(file: FileScan, pattern: RegExp): string[] {
+  const hits: string[] = []
+  for (const line of file.contents.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue
+    if (pattern.test(line)) hits.push(line)
+  }
+  return hits
+}
+
+describe('No Math.random in security paths', () => {
+  it('Math.random must not appear in core/utils, core/engine, core/persistence, core/contracts, strategies', () => {
+    const offenders = ALL_FILES.filter((f) => isSecurityPath(f.path)).flatMap((f) =>
+      linesContaining(f, /\bMath\.random\b/).map((l) => `${f.path}: ${l.trim()}`),
+    )
+    expect(offenders).toEqual([])
+  })
+})
+
+describe('Upload IDs come from a CSPRNG, never Math.random', () => {
+  it('id.ts uses randomUUID + getRandomValues; no Math.random in code', () => {
+    const id = ALL_FILES.find((f) => f.path === 'core/utils/id.ts')
+    expect(id).toBeDefined()
+    if (!id) return
+    expect(id.contents).toMatch(/\brandomUUID\b/)
+    expect(id.contents).toMatch(/\bgetRandomValues\b/)
+    // Use linesContaining so the docstring mention ("Math.random is deliberately
+    // NOT used") doesn't flag - we only inspect code lines.
+    expect(linesContaining(id, /Math\.random/)).toEqual([])
+  })
+})
+
+describe('Every strategy with a backend-supplied URL routes it through validateUploadUrl', () => {
+  it('multipart strategy imports validateUploadUrl', () => {
+    const f = ALL_FILES.find((f) => f.path === 'strategies/multipart/index.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/validateUploadUrl/)
+  })
+  it('post strategy imports validateUploadUrl', () => {
+    const f = ALL_FILES.find((f) => f.path === 'strategies/post/index.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/validateUploadUrl/)
+  })
+})
+
+describe('Persistence deserializer guards against NaN / Infinity / negative byte counts', () => {
+  it('persistence.ts uses Number.isFinite on numeric fields', () => {
+    const f = ALL_FILES.find((f) => f.path === 'core/persistence/persistence.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/Number\.isFinite|isFiniteNumber/)
+  })
+})
+
+describe('Persistence adapters strip dangerous keys before deserialization', () => {
+  it('LocalStorageAdapter applies stripDangerousKeys to JSON.parse output', () => {
+    const f = ALL_FILES.find((f) => f.path === 'core/persistence/adapters.local.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/stripDangerousKeys\(JSON\.parse/)
+  })
+  it('IndexedDB adapter applies stripDangerousKeys to read result', () => {
+    const f = ALL_FILES.find((f) => f.path === 'core/persistence/adapters.indexeddb.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/stripDangerousKeys/)
+  })
+})
+
+describe('UploadEngineError uses static messages (SEC-003)', () => {
+  it('errors.ts does NOT interpolate tainted values into Error.message', () => {
+    const f = ALL_FILES.find((f) => f.path === 'core/errors.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    // The constructor must lookup STATIC_MESSAGES[code] - no template-string interpolation
+    // of caller-supplied context values into the super() call.
+    expect(f.contents).toMatch(/STATIC_MESSAGES\[code\]/)
+  })
+})
+
+describe('Filename sanitization is wired into addFiles', () => {
+  it('create-intent.ts calls sanitizeFilename', () => {
+    const f = ALL_FILES.find((f) => f.path === 'core/engine/store/handlers/create-intent.ts')
+    expect(f).toBeDefined()
+    if (!f) return
+    expect(f.contents).toMatch(/sanitizeFilename/)
+  })
+})
+
+describe('No console.log in security paths (use console.warn for visibility)', () => {
+  it('security paths never call console.log', () => {
+    const offenders = ALL_FILES.filter((f) => isSecurityPath(f.path)).flatMap((f) =>
+      linesContaining(f, /\bconsole\.log\b/).map((l) => `${f.path}: ${l.trim()}`),
+    )
+    expect(offenders).toEqual([])
+  })
+})

package/src/__tests__/store-libs.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test, vi } from 'vitest'
+import { resolveUploadConfig } from '../core/client'
+import {
+  calculateFileChecksum,
+  isAbortError,
+  isMultipartIntent,
+  normalizeError,
+  retryDecision,
+} from '../core/engine/store/store.libs'
+
+describe('normalizeError', () => {
+  test('honors a custom normalizer', () => {
+    const err = normalizeError('anything', () => ({ code: 'auth', message: 'no', retryable: false }))
+    expect(err.code).toBe('auth')
+  })
+
+  test('classifies abort-shaped errors as aborted/non-retryable', () => {
+    const err = normalizeError({ code: 'aborted', reason: 'cancel' })
+    expect(err.code).toBe('aborted')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('thrown value with statusCode alias classifies as http', () => {
+    const err = normalizeError({ statusCode: 503, message: 'down' })
+    expect(err.code).toBe('http')
+    expect((err as { status?: number }).status).toBe(503)
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 5xx is retryable', () => {
+    const err = normalizeError({ status: 503, message: 'down' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 429 is retryable', () => {
+    const err = normalizeError({ status: 429, message: 'slow down' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 400 is not retryable', () => {
+    const err = normalizeError({ status: 400, message: 'bad' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('falls back to unknown non-retryable', () => {
+    const err = normalizeError({})
+    expect(err.code).toBe('unknown')
+    expect(err.retryable).toBe(false)
+  })
+})
+
+describe('retryDecision', () => {
+  const config = resolveUploadConfig({ maxAttempts: 3 })
+
+  test('auth errors never retry', () => {
+    expect(
+      retryDecision(config, { phase: 'intent', attempt: 1, error: { code: 'auth', message: '' } as never }),
+    ).toEqual({
+      retryable: false,
+    })
+  })
+
+  test('validation_failed never retries', () => {
+    expect(
+      retryDecision(config, {
+        phase: 'intent',
+        attempt: 1,
+        error: { code: 'validation_failed', message: '', reason: { code: 'empty_file' } } as never,
+      }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('aborted never retries', () => {
+    expect(
+      retryDecision(config, { phase: 'upload', attempt: 1, error: { code: 'aborted', message: '' } as never }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('stops retrying once attempt >= maxAttempts', () => {
+    expect(
+      retryDecision(config, { phase: 'upload', attempt: 3, error: { code: 'network', message: '' } as never }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('exponential backoff escalates by attempt', () => {
+    const a1 = retryDecision(config, { phase: 'upload', attempt: 1, error: { code: 'network', message: '' } as never })
+    const a2 = retryDecision(config, { phase: 'upload', attempt: 2, error: { code: 'network', message: '' } as never })
+    expect(a1.retryable).toBe(true)
+    expect(a2.retryable).toBe(true)
+    if (a1.retryable && a2.retryable) {
+      expect(a2.delayMs).toBeGreaterThan(a1.delayMs ?? 0)
+    }
+  })
+})
+
+describe('isAbortError', () => {
+  test('matches the aborted shape', () => {
+    expect(isAbortError({ code: 'aborted' })).toBe(true)
+    expect(isAbortError({ code: 'aborted', reason: 'pause' })).toBe(true)
+  })
+
+  test('rejects other shapes', () => {
+    expect(isAbortError(null)).toBe(false)
+    expect(isAbortError({})).toBe(false)
+    expect(isAbortError({ code: 'http' })).toBe(false)
+  })
+})
+
+describe('isMultipartIntent', () => {
+  test('accepts a complete multipart intent', () => {
+    expect(isMultipartIntent({ strategy: 'multipart', fileId: 'f', uploadId: 'u', partSize: 1 })).toBe(true)
+  })
+
+  test('rejects when fields are missing', () => {
+    expect(isMultipartIntent({ strategy: 'multipart' })).toBe(false)
+    expect(isMultipartIntent({ strategy: 'post', fileId: 'f', uploadId: 'u' })).toBe(false)
+  })
+})
+
+describe('calculateFileChecksum', () => {
+  /** Reference digest via native Web Crypto for cross-checking the incremental path. */
+  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('')
+  }
+
+  test('produces a hex digest', async () => {
+    const file = new File([new Uint8Array([0, 1, 2, 3])], 'a.bin')
+    const h = await calculateFileChecksum(file)
+    expect(h).toMatch(/^[0-9a-f]{64}$/)
+  })
+
+  test('different files produce different hashes', async () => {
+    const a = new File([new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 9])], 'a.bin')
+    const b = new File([new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 1])], 'b.bin')
+    const ha = await calculateFileChecksum(a)
+    const hb = await calculateFileChecksum(b)
+    expect(ha).not.toBe(hb)
+  })
+
+  test('file at the boundary uses the inline Web Crypto path (arrayBuffer once)', async () => {
+    const bytes = new Uint8Array(64)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = i
+    const file = new File([bytes], 'cap.bin')
+    const abSpy = vi.spyOn(file, 'arrayBuffer')
+    const h = await calculateFileChecksum(file, 64) // size 64, boundary 64 -> inline
+    expect(h).toBe(await subtleHex(bytes))
+    expect(abSpy).toHaveBeenCalledTimes(1)
+  })
+
+  test('file below the boundary uses the inline Web Crypto path', async () => {
+    const bytes = new Uint8Array(32)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 3) & 0xff
+    const file = new File([bytes], 'small.bin')
+    const abSpy = vi.spyOn(file, 'arrayBuffer')
+    const h = await calculateFileChecksum(file, 64) // size 32 < boundary 64
+    expect(h).toBe(await subtleHex(bytes))
+    expect(abSpy).toHaveBeenCalledTimes(1)
+  })
+
+  test('file above the boundary is hashed incrementally and matches Web Crypto', async () => {
+    const bytes = new Uint8Array(128)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 7) & 0xff
+    const file = new File([bytes], 'big.bin')
+    // No Worker in the test realm -> inline-incremental over slices.
+    const h = await calculateFileChecksum(file, 16) // size 128 > boundary 16
+    expect(h).toBe(await subtleHex(bytes))
+  })
+
+  test('incremental path is stable across boundary/chunk splits', async () => {
+    const bytes = new Uint8Array(1000)
+    for (let i = 0; i < bytes.length; i++) bytes[i] = (i * 31 + 7) & 0xff
+    const file = new File([bytes], 'span.bin')
+    const expected = await subtleHex(bytes)
+    // Force incremental with several different sub-cap boundaries.
+    for (const boundary of [1, 7, 13, 64, 100]) {
+      const h = await calculateFileChecksum(file, boundary)
+      expect(h).toBe(expected)
+    }
+  })
+
+  test('maxSize of 0 or null falls back to the default boundary', async () => {
+    const file = new File([new Uint8Array([1, 2, 3])], 'tiny.bin')
+    const h = await calculateFileChecksum(file, 0)
+    expect(h).toMatch(/^[0-9a-f]{64}$/)
+  })
+})