@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/engine/validation/list.ts

@@ -1,16 +1,25 @@
-import type { UploadConfig } from '../../client'
-import type { RejectReason } from '../../contracts'
+import type { Contracts } from '../../contracts'
+import type { Engine } from '../engine.types'
 import { validateFile } from './file'
 
+/**
+ * Validates an intent object from the backend.
+ * Ensures required fields are present and URLs are valid.
+ *
+ * @param intent - Intent object to validate
+ * @param strategy - Expected strategy type (from the intent itself)
+ *
+ * @returns {Error | null} Error if validation fails, null if valid
+ */
 export function validateFileList<P extends string>(
   files: File[],
   purpose: P,
-  config: UploadConfig<P>,
+  config: Engine.Config<P>,
   existingCount: number = 0,
-): { valid: File[]; rejected: Array<{ file: File; reason: RejectReason }> } {
+): { valid: File[]; rejected: Array<{ file: File; reason: Contracts.Validation.Rejection }> } {
   const rules = config.validation?.[purpose]
   const valid: File[] = []
-  const rejected: Array<{ file: File; reason: RejectReason }> = []
+  const rejected: Array<{ file: File; reason: Contracts.Validation.Rejection }> = []
 
   // Calculate remaining slots based on maxFiles limit
   const maxFiles = rules?.maxFiles
@@ -38,13 +47,3 @@ export function validateFileList<P extends string>(
 
   return { valid, rejected }
 }
-
-/**
- * Validates an intent object from the backend.
- * Ensures required fields are present and URLs are valid.
- *
- * @param intent - Intent object to validate
- * @param strategy - Expected strategy type (from the intent itself)
- *
- * @returns {Error | null} Error if validation fails, null if valid
- */

package/src/core/engine/validation/mime.ts

@@ -0,0 +1,39 @@
+import type { Contracts } from '../../contracts'
+import { __mimeWarnings, mimeMatches, sniffMime } from '../../utils/mime-sniff'
+
+/**
+ * Cross-check the claimed `file.type` against the file's magic bytes. Reads the
+ * first 16 bytes only (the longest signature {@link sniffMime} handles is 12).
+ *
+ * @returns A `mime_mismatch` reject reason when `strict` is `true` and the
+ *   sniff disagrees. Returns `null` (allow) when the sniff is inconclusive, the
+ *   claim matches, or `strict` is `false` — in the non-strict case a one-time
+ *   warning is logged per mismatched pair. Empty files resolve to `null`.
+ */
+export async function validateMimeSignature(
+  file: File,
+  strict: boolean,
+): Promise<Contracts.Validation.Rejection | null> {
+  if (file.size === 0) return null
+  // 16 bytes covers every recognised signature (longest is 12).
+  const head = await file.slice(0, 16).arrayBuffer()
+  const sniffed = sniffMime(new Uint8Array(head))
+  if (sniffed === null) return null
+  const claimed = file.type || ''
+  if (mimeMatches(claimed, sniffed)) return null
+
+  if (strict) {
+    return { code: 'mime_mismatch', claimed: claimed || '<empty>', sniffed }
+  }
+
+  const key = `${claimed || '<empty>'}::${sniffed}`
+  if (!__mimeWarnings.has(key)) {
+    __mimeWarnings.add(key)
+    // Filename is omitted from the warning: it is untrusted input.
+    console.warn(
+      `[duck-upload] MIME mismatch: claimed "${claimed || '<empty>'}" but bytes look like "${sniffed}". ` +
+        'Set `strictMimeMatch: true` to reject these files.',
+    )
+  }
+  return null
+}

package/src/core/errors.ts

@@ -0,0 +1,271 @@
+import type { Contracts } from './contracts'
+
+/**
+ * Structured extra context properties for upload errors.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export type UploadErrorContext = Record<string, unknown>
+
+const STATIC_MESSAGES: Record<string, string> = {
+  intent_failed: 'upload intent request failed',
+  upload_failed: 'upload transfer failed',
+  complete_failed: 'upload finalize failed',
+  validation_failed: 'file validation failed',
+  strategy_missing: 'upload strategy not found',
+  aborted: 'upload aborted',
+  network: 'network error occurred',
+  http: 'http request failed',
+  timeout: 'request timed out',
+  auth: 'authentication failed',
+  rate_limit: 'rate limit exceeded',
+  server: 'server error occurred',
+  unknown: 'unknown upload error',
+}
+
+/**
+ * Base typed error thrown by the upload engine.
+ *
+ * Always carries a stable error classification `code` and an immutable, static
+ * `message`. Attic strings (like raw input details) live under `context` or subclass-specific fields.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadEngineError extends Error {
+  /** Stable machine-readable error code. */
+  readonly code: string
+  /** Structured context details. */
+  readonly context?: UploadErrorContext
+  /** Original error, if any, mapped per ES2022. */
+  override readonly cause?: unknown
+  /** Flag specifying whether the error recovery system should schedule retries. */
+  readonly retryable: boolean
+
+  constructor(
+    code: string,
+    init?: {
+      message?: string | undefined
+      context?: UploadErrorContext | undefined
+      cause?: unknown
+      retryable?: boolean | undefined
+    },
+  ) {
+    const msg = init?.message ?? STATIC_MESSAGES[code] ?? `upload error (${code})`
+    super(msg)
+    this.name = 'UploadEngineError'
+    this.code = code
+    this.retryable = init?.retryable ?? false
+    if (init?.context) this.context = init.context
+    if (init?.cause !== undefined) this.cause = init.cause
+  }
+}
+
+/**
+ * Error thrown when file validation rules fail.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadValidationError extends UploadEngineError {
+  /** Structured rejection reason details. */
+  readonly reason: Contracts.Validation.Rejection
+
+  constructor(
+    reason: Contracts.Validation.Rejection,
+    message?: string,
+    init?: { cause?: unknown; context?: UploadErrorContext },
+  ) {
+    super('validation_failed', {
+      message: message ?? `File validation failed: ${reason.code}`,
+      retryable: false,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadValidationError'
+    this.reason = reason
+  }
+}
+
+/**
+ * Error thrown when an upload strategy identifier is not registered.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadStrategyMissingError extends UploadEngineError {
+  /** Unregistered strategy identifier. */
+  readonly strategy: string
+
+  constructor(strategy: string, message?: string, init?: { cause?: unknown; context?: UploadErrorContext }) {
+    super('strategy_missing', {
+      message: message ?? `Upload strategy "${strategy}" is not registered`,
+      retryable: false,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadStrategyMissingError'
+    this.strategy = strategy
+  }
+}
+
+/**
+ * Error thrown when an upload is aborted (paused or canceled).
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadAbortError extends UploadEngineError {
+  /** Reason context for the abort. */
+  readonly reason: 'pause' | 'cancel' | 'unknown'
+
+  constructor(
+    reason: 'pause' | 'cancel' | 'unknown',
+    message?: string,
+    init?: { cause?: unknown; context?: UploadErrorContext },
+  ) {
+    super('aborted', {
+      message: message ?? 'Upload aborted',
+      retryable: false,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadAbortError'
+    this.reason = reason
+  }
+}
+
+/**
+ * Error thrown on transport-level connection or fetch failures.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadNetworkError extends UploadEngineError {
+  constructor(message?: string, init?: { cause?: unknown; context?: UploadErrorContext }) {
+    super('network', {
+      message: message ?? 'Network error occurred',
+      retryable: true,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadNetworkError'
+  }
+}
+
+/**
+ * Error thrown when a non-2xx HTTP status response is returned.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadHttpError extends UploadEngineError {
+  /** HTTP response status code. */
+  readonly status: number
+  /** HTTP response status text message. */
+  readonly statusText?: string
+
+  constructor(
+    status: number,
+    message?: string,
+    init?: {
+      statusText?: string | undefined
+      cause?: unknown
+      context?: UploadErrorContext | undefined
+      retryable?: boolean | undefined
+    },
+  ) {
+    const isRetryable = init?.retryable ?? (status >= 500 || status === 429)
+    super('http', {
+      message: message ?? `HTTP request failed with status ${status}`,
+      retryable: isRetryable,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadHttpError'
+    this.status = status
+    if (init?.statusText) this.statusText = init.statusText
+  }
+}
+
+/**
+ * Error thrown when a timeout occurs during network operations.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadTimeoutError extends UploadEngineError {
+  constructor(message?: string, init?: { cause?: unknown; context?: UploadErrorContext }) {
+    super('timeout', {
+      message: message ?? 'Request timed out',
+      retryable: true,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadTimeoutError'
+  }
+}
+
+/**
+ * Error thrown on authentication / authorization failures.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadAuthError extends UploadEngineError {
+  constructor(message?: string, init?: { cause?: unknown; context?: UploadErrorContext }) {
+    super('auth', {
+      message: message ?? 'Authentication failed',
+      retryable: false,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadAuthError'
+  }
+}
+
+/**
+ * Error thrown when the endpoint indicates rate limits are exceeded.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadRateLimitError extends UploadEngineError {
+  /** Optional delay value recommended by the server before retry. */
+  readonly retryAfterMs?: number
+
+  constructor(message?: string, init?: { retryAfterMs?: number; cause?: unknown; context?: UploadErrorContext }) {
+    super('rate_limit', {
+      message: message ?? 'Rate limit exceeded',
+      retryable: true,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadRateLimitError'
+    if (init?.retryAfterMs !== undefined) this.retryAfterMs = init.retryAfterMs
+  }
+}
+
+/**
+ * Error thrown when custom backend/server validation errors are reported.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadServerError extends UploadEngineError {
+  /** Server-defined diagnostic code. */
+  readonly serverCode?: string
+
+  constructor(message?: string, init?: { serverCode?: string; cause?: unknown; context?: UploadErrorContext }) {
+    super('server', {
+      message: message ?? 'Server error occurred',
+      retryable: true,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadServerError'
+    if (init?.serverCode) this.serverCode = init.serverCode
+  }
+}
+
+/**
+ * Fallback error class for unclassified or legacy throws.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export class UploadUnknownError extends UploadEngineError {
+  constructor(message?: string, init?: { cause?: unknown; context?: UploadErrorContext }) {
+    super('unknown', {
+      message: message ?? 'Unknown upload error',
+      retryable: false,
+      cause: init?.cause,
+      context: init?.context,
+    })
+    this.name = 'UploadUnknownError'
+  }
+}
+
+/**
+ * Runtime error stored on items and passed through engine events.
+ * Plain contract shapes and {@link UploadEngineError} subclasses are both valid.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export type UploadError = Contracts.Errors.Error | UploadEngineError

package/src/core/index.ts

@@ -1,5 +1,28 @@
-export * from './client'
-export * from './contracts'
-export * from './engine'
-export * from './persistence'
-export * from './utils'
+export { resolveUploadConfig } from './client'
+export type { Contracts, Transport } from './contracts'
+export { createFetchTransport, createXHRTransport } from './contracts'
+export type { Store } from './engine'
+export { createUploadStore, Engine } from './engine'
+export type { UploadError, UploadErrorContext } from './errors'
+export {
+  UploadAbortError,
+  UploadAuthError,
+  UploadEngineError,
+  UploadHttpError,
+  UploadNetworkError,
+  UploadRateLimitError,
+  UploadServerError,
+  UploadStrategyMissingError,
+  UploadTimeoutError,
+  UploadUnknownError,
+  UploadValidationError,
+} from './errors'
+export type { UploadPersistence } from './persistence'
+export {
+  createMemoryAdapter,
+  deserializeSnapshot,
+  IndexedDBAdapter,
+  LocalStorageAdapter,
+  MemoryAdapter,
+  serializeSnapshot,
+} from './persistence'

package/src/core/persistence/__tests__/deserialize-nan-bypass.test.ts

@@ -0,0 +1,100 @@
+/**
+ * NaN-bypass defense for the persistence deserializer. A persisted
+ * `size: NaN`, `lastModified: NaN`, `pct: NaN`, or negative byte count
+ * would land in the deserialized state and break downstream math
+ * (`uploadedBytes / totalBytes` → NaN, comparisons silently false).
+ * Every numeric field must pass `Number.isFinite` + non-negative.
+ */
+
+import { describe, expect, test } from 'vitest'
+import { deserializeSnapshot } from '../persistence'
+
+function makeOpts(strategy = 'post') {
+  return {
+    isPurpose: (v: string): v is string => typeof v === 'string',
+    isIntent: (v: unknown): v is { strategy: string; fileId: string } =>
+      typeof v === 'object' && v !== null && 'strategy' in v,
+    hasStrategy: (v: string) => v === strategy,
+  }
+}
+
+const okItem = {
+  id: 'u1',
+  purpose: 'avatar',
+  status: 'paused',
+  file: { name: 'a.txt', size: 100, type: 'text/plain', lastModified: 1700000000 },
+  intent: { strategy: 'post', fileId: 'f' },
+  cursor: { strategy: 'post' },
+  progress: { uploadedBytes: 50, totalBytes: 100, pct: 50 },
+}
+
+describe('deserializeSnapshot - NaN-bypass defense', () => {
+  test('NaN version rejects snapshot', () => {
+    const raw = { version: Number.NaN, createdAt: 1, items: { u1: okItem } }
+    expect(deserializeSnapshot(raw, makeOpts())).toBeNull()
+  })
+
+  test('Infinity createdAt rejects snapshot', () => {
+    const raw = { version: 1, createdAt: Number.POSITIVE_INFINITY, items: { u1: okItem } }
+    expect(deserializeSnapshot(raw, makeOpts())).toBeNull()
+  })
+
+  test('NaN file.size drops the item (other items still load)', () => {
+    const raw = {
+      version: 1,
+      createdAt: 1,
+      items: {
+        u1: { ...okItem, file: { ...okItem.file, size: Number.NaN } },
+        u2: { ...okItem, id: 'u2' },
+      },
+    }
+    const state = deserializeSnapshot(raw, makeOpts())
+    expect(state).not.toBeNull()
+    expect(state?.items.has('u1')).toBe(false)
+    expect(state?.items.has('u2')).toBe(true)
+  })
+
+  test('negative size drops the item', () => {
+    const raw = {
+      version: 1,
+      createdAt: 1,
+      items: { u1: { ...okItem, file: { ...okItem.file, size: -1 } } },
+    }
+    const state = deserializeSnapshot(raw, makeOpts())
+    expect(state?.items.has('u1')).toBe(false)
+  })
+
+  test('NaN lastModified drops the item', () => {
+    const raw = {
+      version: 1,
+      createdAt: 1,
+      items: { u1: { ...okItem, file: { ...okItem.file, lastModified: Number.NaN } } },
+    }
+    const state = deserializeSnapshot(raw, makeOpts())
+    expect(state?.items.has('u1')).toBe(false)
+  })
+
+  test('NaN progress.uploadedBytes drops progress (item still loads with zero)', () => {
+    const raw = {
+      version: 1,
+      createdAt: 1,
+      items: {
+        u1: { ...okItem, progress: { ...okItem.progress, uploadedBytes: Number.NaN } },
+      },
+    }
+    const state = deserializeSnapshot(raw, makeOpts())
+    expect(state?.items.has('u1')).toBe(true)
+    const item = state?.items.get('u1') as { progress?: { uploadedBytes: number } } | undefined
+    expect(item?.progress?.uploadedBytes).toBe(0)
+  })
+
+  test('empty MIME type is allowed (browsers may return empty for unknown)', () => {
+    const raw = {
+      version: 1,
+      createdAt: 1,
+      items: { u1: { ...okItem, file: { ...okItem.file, type: '' } } },
+    }
+    const state = deserializeSnapshot(raw, makeOpts())
+    expect(state?.items.has('u1')).toBe(true)
+  })
+})

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

@@ -0,0 +1,85 @@
+/**
+ * Defense against prototype-pollution via persisted snapshots. Round-trip
+ * tests live in `src/__test__/persistence.test.ts`; this file is scoped to
+ * security regressions.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { isRecord } from '../../utils/guards'
+import { LocalStorageAdapter } from '../adapters.local'
+
+type LocalStorageStub = {
+  store: Record<string, string>
+  getItem: (key: string) => string | null
+  setItem: (key: string, value: string) => void
+  removeItem: (key: string) => void
+  clear: () => void
+}
+
+function installLocalStorageStub(): LocalStorageStub {
+  const stub: LocalStorageStub = {
+    store: {},
+    getItem(key) {
+      return Object.prototype.hasOwnProperty.call(this.store, key) ? (this.store[key] ?? null) : null
+    },
+    setItem(key, value) {
+      this.store[key] = String(value)
+    },
+    removeItem(key) {
+      delete this.store[key]
+    },
+    clear() {
+      this.store = {}
+    },
+  }
+  ;(globalThis as unknown as { localStorage: LocalStorageStub }).localStorage = stub
+  return stub
+}
+
+describe('LocalStorageAdapter prototype-pollution defense', () => {
+  let stub: LocalStorageStub
+
+  beforeEach(() => {
+    stub = installLocalStorageStub()
+  })
+
+  afterEach(() => {
+    // Defensive cleanup in case a test forgot to.
+    delete (Object.prototype as Record<string, unknown>)['polluted']
+    delete (Object.prototype as Record<string, unknown>)['rce']
+  })
+
+  test('a {"__proto__":{"polluted":true}} payload does NOT pollute Object.prototype after load', async () => {
+    stub.store['snap'] = '{"__proto__":{"polluted":true}}'
+    const loaded = await LocalStorageAdapter.load('snap')
+    expect(loaded).not.toBeNull()
+    expect(({} as Record<string, unknown>)['polluted']).toBeUndefined()
+    expect(Object.prototype.hasOwnProperty.call(loaded as object, '__proto__')).toBe(false)
+  })
+
+  test('a {"constructor":{"prototype":{"polluted":true}}} payload does NOT pollute', async () => {
+    stub.store['snap'] = '{"constructor":{"prototype":{"rce":true}}}'
+    const loaded = await LocalStorageAdapter.load('snap')
+    expect(loaded).not.toBeNull()
+    expect(({} as Record<string, unknown>)['rce']).toBeUndefined()
+    expect(Object.prototype.hasOwnProperty.call(loaded as object, 'constructor')).toBe(false)
+  })
+
+  test('array-shaped persisted value is rejected by isRecord (no spread into state)', async () => {
+    stub.store['snap'] = '[1,2,3]'
+    const loaded = await LocalStorageAdapter.load('snap')
+    expect(Array.isArray(loaded)).toBe(true)
+    expect(isRecord(loaded)).toBe(false)
+  })
+
+  test('happy path: a plain-object snapshot hydrates fine', async () => {
+    stub.store['snap'] = JSON.stringify({ version: 1, createdAt: 100, items: { x: { id: 'x', v: 1 } } })
+    const loaded = (await LocalStorageAdapter.load('snap')) as Record<string, unknown>
+    expect(loaded).toEqual({ version: 1, createdAt: 100, items: { x: { id: 'x', v: 1 } } })
+    expect(isRecord(loaded)).toBe(true)
+  })
+
+  test('malformed JSON returns null', async () => {
+    stub.store['snap'] = '{not-json'
+    expect(await LocalStorageAdapter.load('snap')).toBeNull()
+  })
+})

package/src/core/persistence/adapters.indexeddb.ts

@@ -1,4 +1,5 @@
-import type { PersistenceAdapter } from './persistence.types'
+import { stripDangerousKeys } from '../utils/guards'
+import type { UploadPersistence } from './persistence.types'
 
 const DB_NAME = 'upload-engine'
 const STORE = 'snapshots'
@@ -33,7 +34,12 @@ function txDone(tx: IDBTransaction): Promise<void> {
   })
 }
 
-export const IndexedDBAdapter: PersistenceAdapter = {
+/**
+ * Persistence adapter backed by IndexedDB, for durable snapshot storage in the
+ * browser without the size limits of `localStorage`.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export const IndexedDBAdapter: UploadPersistence.Adapter = {
   async load(key) {
     if (typeof indexedDB === 'undefined') return null
     const db = await openDB()
@@ -43,7 +49,7 @@ export const IndexedDBAdapter: PersistenceAdapter = {
     try {
       const value = await reqToPromise(store.get(key))
       await txDone(tx)
-      return value ?? null
+      return value === undefined || value === null ? null : stripDangerousKeys(value)
     } catch {
       try {
         await txDone(tx)

package/src/core/persistence/adapters.local.ts

@@ -1,12 +1,18 @@
-import type { PersistenceAdapter } from './persistence.types'
+import { stripDangerousKeys } from '../utils/guards'
+import type { UploadPersistence } from './persistence.types'
 
-export const LocalStorageAdapter: PersistenceAdapter = {
+/**
+ * Persistence adapter backed by `localStorage`. Synchronous and simple; best
+ * suited to small snapshots.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export const LocalStorageAdapter: UploadPersistence.Adapter = {
   load(key) {
     if (typeof localStorage === 'undefined') return null
     const raw = localStorage.getItem(key)
     if (!raw) return null
     try {
-      return JSON.parse(raw)
+      return stripDangerousKeys(JSON.parse(raw))
     } catch {
       return null
     }

package/src/core/persistence/adapters.memory.ts

@@ -1,15 +1,37 @@
-import type { PersistenceAdapter } from './persistence.types'
+import type { UploadPersistence } from './persistence.types'
 
-const store = new Map<string, unknown>()
-
-export const MemoryAdapter: PersistenceAdapter = {
-  load(key) {
-    return store.get(key) ?? null
-  },
-  save(key, snapshot) {
-    store.set(key, snapshot)
-  },
-  clear(key) {
-    store.delete(key)
-  },
+/**
+ * Create an in-memory {@link PersistenceAdapter} backed by a fresh `Map`.
+ *
+ * Each call returns an isolated store. Multi-engine and multi-tenant
+ * deployments must use the factory so engine instances cannot read or
+ * overwrite each other's snapshots.
+ *
+ * @example
+ * ```ts
+ * const adapter = createMemoryAdapter()
+ * createUploadStore({ persistence: { adapter, key: 'tenant-a' } })
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createMemoryAdapter(): UploadPersistence.Adapter {
+  const store = new Map<string, unknown>()
+  return {
+    load(key) {
+      return store.get(key) ?? null
+    },
+    save(key, snapshot) {
+      store.set(key, snapshot)
+    },
+    clear(key) {
+      store.delete(key)
+    },
+  }
 }
+
+/**
+ * Shared in-memory adapter instance. Convenient for single-engine apps; use
+ * {@link createMemoryAdapter} when isolation between engines is required.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export const MemoryAdapter = createMemoryAdapter()