@gentleduck/upload 0.2.6 → 0.3.0

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/{__test__ → __tests__}/store-libs.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test, vi } from 'vitest'
 import { resolveUploadConfig } from '../core/client'
 import {
   calculateFileChecksum,
@@ -121,11 +121,18 @@ describe('isMultipartIntent', () => {
 })
 
 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]+$/)
-    expect(h.length).toBeGreaterThan(0)
+    expect(h).toMatch(/^[0-9a-f]{64}$/)
   })
 
   test('different files produce different hashes', async () => {
@@ -135,4 +142,51 @@ describe('calculateFileChecksum', () => {
     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}$/)
+  })
 })

package/src/__tests__/transport-fetch.test.ts

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { createFetchTransport } from '../core/contracts/transport'
+import { UploadAbortError } from '../core/contracts/transport/transport.libs'
+
+const URL_OK = 'https://up.example.com/o'
+
+function stubFetch(impl: (url: string, init: RequestInit) => Promise<Response> | Response) {
+  const fn = vi.fn(impl)
+  vi.stubGlobal('fetch', fn)
+  return fn
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createFetchTransport.put', () => {
+  test('PUTs the body and returns the ETag', async () => {
+    const fetchMock = stubFetch(() => new Response(null, { status: 200, headers: { ETag: '"deadbeef"' } }))
+    const t = createFetchTransport()
+    const onProgress = vi.fn()
+    const out = await t.put({
+      url: URL_OK,
+      body: new Blob([new Uint8Array(10)]),
+      headers: { 'Content-Type': 'application/octet-stream' },
+      signal: new AbortController().signal,
+      onProgress,
+    })
+
+    expect(out.etag).toBe('deadbeef')
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(url).toBe(URL_OK)
+    expect(init.method).toBe('PUT')
+    // Terminal progress tick.
+    expect(onProgress).toHaveBeenCalledWith(10, 10)
+  })
+
+  test('rejects non-2xx with the status', async () => {
+    stubFetch(() => new Response('nope', { status: 500 }))
+    const t = createFetchTransport()
+    await expect(t.put({ url: URL_OK, body: new Blob(['x']), signal: new AbortController().signal })).rejects.toThrow(
+      /status 500/,
+    )
+  })
+
+  test('rejects a relative URL', async () => {
+    stubFetch(() => new Response(null, { status: 200 }))
+    const t = createFetchTransport()
+    await expect(
+      t.put({ url: '/relative', body: new Blob(['x']), signal: new AbortController().signal }),
+    ).rejects.toThrow(/absolute URL/)
+  })
+
+  test('maps an aborted signal to UploadAbortError', async () => {
+    stubFetch(() => new Response(null, { status: 200 }))
+    const controller = new AbortController()
+    controller.abort('cancel')
+    const t = createFetchTransport()
+    await expect(t.put({ url: URL_OK, body: new Blob(['x']), signal: controller.signal })).rejects.toBeInstanceOf(
+      UploadAbortError,
+    )
+  })
+})
+
+describe('createFetchTransport.postForm', () => {
+  test('sends multipart form data', async () => {
+    const fetchMock = stubFetch(() => new Response(null, { status: 204 }))
+    const t = createFetchTransport()
+    await t.postForm({
+      url: URL_OK,
+      fields: { key: 'v', policy: 'p' },
+      file: new File(['abc'], 'a.txt'),
+      signal: new AbortController().signal,
+    })
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]
+    expect(init.method).toBe('POST')
+    expect(init.body).toBeInstanceOf(FormData)
+  })
+})
+
+describe('createFetchTransport.get', () => {
+  test('streams the body and reports incremental progress', async () => {
+    const payload = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8])
+    stubFetch(
+      () =>
+        new Response(payload, {
+          status: 200,
+          headers: { 'Content-Length': String(payload.length), 'Content-Type': 'application/octet-stream' },
+        }),
+    )
+    const t = createFetchTransport()
+    const onProgress = vi.fn()
+    const out = await t.get?.({ url: URL_OK, signal: new AbortController().signal, onProgress })
+    expect(out?.status).toBe(200)
+    const bytes = new Uint8Array(await out!.blob.arrayBuffer())
+    expect(Array.from(bytes)).toEqual(Array.from(payload))
+    // Final progress equals total.
+    const last = onProgress.mock.calls.at(-1)
+    expect(last?.[0]).toBe(payload.length)
+    expect(last?.[1]).toBe(payload.length)
+  })
+
+  test('rejects a failed download', async () => {
+    stubFetch(() => new Response('nope', { status: 404 }))
+    const t = createFetchTransport()
+    await expect(t.get?.({ url: URL_OK, signal: new AbortController().signal })).rejects.toThrow(/status 404/)
+  })
+})

package/src/{__test__ → __tests__}/transport.test.ts

@@ -89,7 +89,7 @@ describe('createXHRTransport.put', () => {
       headers: { 'x-foo': 'bar' },
     })
 
-    const xhr = MockXHR.instances[0]
+    const xhr = MockXHR.instances[0]!
     expect(xhr.method).toBe('PUT')
     expect(xhr.url).toBe('https://example.com/part')
     expect(xhr.headers['x-foo']).toBe('bar')
@@ -104,7 +104,7 @@ describe('createXHRTransport.put', () => {
     const ctl = new AbortController()
     const promise = t.put({ url: 'https://example.com/part', body: new Blob(['x']), signal: ctl.signal })
 
-    const xhr = MockXHR.instances[0]
+    const xhr = MockXHR.instances[0]!
     xhr.fireSuccess(503)
     await expect(promise).rejects.toThrow(/status 503/)
   })
@@ -114,7 +114,7 @@ describe('createXHRTransport.put', () => {
     const ctl = new AbortController()
     const promise = t.put({ url: 'https://example.com/part', body: new Blob(['x']), signal: ctl.signal })
 
-    const xhr = MockXHR.instances[0]
+    const xhr = MockXHR.instances[0]!
     xhr.fireError(0)
     await expect(promise).rejects.toThrow(/CORS/)
   })
@@ -148,7 +148,7 @@ describe('createXHRTransport.put', () => {
       onProgress,
     })
 
-    const xhr = MockXHR.instances[0]
+    const xhr = MockXHR.instances[0]!
     xhr.upload.onprogress?.({ lengthComputable: true, loaded: 5, total: 10 } as ProgressEvent)
     expect(onProgress).toHaveBeenCalledWith(5, 10)
 
@@ -169,7 +169,7 @@ describe('createXHRTransport.postForm', () => {
       signal: ctl.signal,
     })
 
-    const xhr = MockXHR.instances[0]
+    const xhr = MockXHR.instances[0]!
     expect(xhr.method).toBe('POST')
     expect(xhr.body).toBeInstanceOf(FormData)
     const form = xhr.body as FormData

package/src/core/__tests__/errors.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'vitest'
+import { UploadEngineError } from '../errors'
+
+const MALICIOUS_FILENAME = '<img src=x onerror=alert(1)>.png'
+
+describe('UploadEngineError', () => {
+  test('message is static, does NOT contain the raw filename', () => {
+    const err = new UploadEngineError('upload_failed', { context: { filename: MALICIOUS_FILENAME } })
+    expect(err.message).not.toContain(MALICIOUS_FILENAME)
+    expect(err.message).not.toContain('<img')
+    expect(err.message).toBe('upload transfer failed')
+  })
+
+  test('context.filename carries the raw filename intact', () => {
+    const err = new UploadEngineError('upload_failed', { context: { filename: MALICIOUS_FILENAME } })
+    expect(err.context?.['filename']).toBe(MALICIOUS_FILENAME)
+  })
+
+  test('is an instance of Error and UploadEngineError; code is preserved', () => {
+    const err = new UploadEngineError('intent_failed')
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('intent_failed')
+    expect(err.name).toBe('UploadEngineError')
+  })
+
+  test('cause is preserved on the ES2022 cause field', () => {
+    const original = new Error('boom')
+    const err = new UploadEngineError('upload_failed', { cause: original })
+    expect(err.cause).toBe(original)
+  })
+
+  test('unknown code falls back to a generic static message', () => {
+    const err = new UploadEngineError('something_new')
+    expect(err.message).toBe('upload error (something_new)')
+    expect(err.code).toBe('something_new')
+  })
+})
+
+describe('engine handlers filename-in-message inverse assertion', () => {
+  // The legacy contract was: `error.message.includes(filename)`. The new
+  // contract is the opposite: the filename MUST NOT appear in `message`. The
+  // handlers no longer interpolate filename into `message`; verifying that by
+  // exercising the handlers directly is covered by the integration suite, but
+  // we keep the contract pinned here so future refactors stay safe.
+  test('a structured error keeps the message clean and surfaces filename only on context', () => {
+    const base = { code: 'unknown' as const, message: 'Unknown error', retryable: false }
+    const error = {
+      ...base,
+      context: { filename: MALICIOUS_FILENAME, size: 12, purpose: 'avatar' },
+    }
+    expect(error.message).not.toContain(MALICIOUS_FILENAME)
+    expect(error.message).not.toContain('<img')
+    expect(error.context['filename']).toBe(MALICIOUS_FILENAME)
+  })
+})
+
+import {
+  UploadAbortError,
+  UploadAuthError,
+  UploadHttpError,
+  UploadNetworkError,
+  UploadRateLimitError,
+  UploadServerError,
+  UploadStrategyMissingError,
+  UploadTimeoutError,
+  UploadUnknownError,
+  UploadValidationError,
+} from '../errors'
+
+describe('UploadEngineError subclasses', () => {
+  test('UploadValidationError', () => {
+    const reason = { code: 'empty_file' as const }
+    const err = new UploadValidationError(reason)
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('validation_failed')
+    expect(err.reason).toBe(reason)
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadStrategyMissingError', () => {
+    const err = new UploadStrategyMissingError('custom')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('strategy_missing')
+    expect(err.strategy).toBe('custom')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadAbortError', () => {
+    const err = new UploadAbortError('pause')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('aborted')
+    expect(err.reason).toBe('pause')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadNetworkError', () => {
+    const err = new UploadNetworkError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('network')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadHttpError', () => {
+    const err = new UploadHttpError(500, 'Internal Server Error', { statusText: 'Server Error' })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('http')
+    expect(err.status).toBe(500)
+    expect(err.statusText).toBe('Server Error')
+    expect(err.retryable).toBe(true)
+
+    const err400 = new UploadHttpError(400, 'Bad Request')
+    expect(err400.retryable).toBe(false)
+  })
+
+  test('UploadTimeoutError', () => {
+    const err = new UploadTimeoutError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('timeout')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadAuthError', () => {
+    const err = new UploadAuthError()
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('auth')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('UploadRateLimitError', () => {
+    const err = new UploadRateLimitError('Too many requests', { retryAfterMs: 5000 })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('rate_limit')
+    expect(err.retryAfterMs).toBe(5000)
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadServerError', () => {
+    const err = new UploadServerError('DB Error', { serverCode: 'DB_ERROR' })
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('server')
+    expect(err.serverCode).toBe('DB_ERROR')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('UploadUnknownError', () => {
+    const err = new UploadUnknownError('Something exploded')
+    expect(err).toBeInstanceOf(UploadEngineError)
+    expect(err.code).toBe('unknown')
+    expect(err.retryable).toBe(false)
+  })
+})

package/src/core/client.ts

@@ -0,0 +1,3 @@
+export { resolveUploadConfig } from './engine/engine.libs'
+export type { Store } from './engine/store'
+export { createUploadStore } from './engine/store'