@gentleduck/upload 0.2.5 → 0.3.0

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

@@ -0,0 +1,156 @@
+/**
+ * SSRF guards for backend-supplied upload URLs.
+ *
+ * Every URL that arrives from a non-trusted backend (presigned POST,
+ * presigned PUT, multipart part URLs) must pass through
+ * `validateUploadUrl` before it reaches the transport. The guard
+ * blocks:
+ *
+ * - Empty / non-string / malformed URLs
+ * - `..` path-traversal segments (URL parser would normalize them away)
+ * - Non-http(s) protocols (`file:`, `javascript:`, `data:`)
+ * - IP literals pointing at loopback / RFC1918 / link-local /
+ *   cloud-metadata / CGNAT / multicast / broadcast addresses
+ * - IPv6 embedded IPv4 (mapped, compat, 6to4, NAT64) carrying any of the above
+ *
+ * DNS rebinding is out of scope for a client-side check.
+ */
+
+function hexTailToDottedQuad(tail: string): string | null {
+  const m = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(tail)
+  if (!m || m[1] === undefined || m[2] === undefined) return null
+  const hi = parseInt(m[1], 16)
+  const lo = parseInt(m[2], 16)
+  if (!Number.isFinite(hi) || !Number.isFinite(lo)) return null
+  if (hi < 0 || hi > 0xffff || lo < 0 || lo > 0xffff) return null
+  return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`
+}
+
+/**
+ * Returns true when `host` is a literal IP address in one of the
+ * private / loopback / cloud-metadata ranges. Hostnames that aren't IP
+ * literals return false.
+ */
+export function isPrivateHost(host: string): boolean {
+  let h = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+  if (h.endsWith('.')) h = h.slice(0, -1)
+
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h)
+  if (v4) {
+    const a = Number(v4[1])
+    const b = Number(v4[2])
+    const c = Number(v4[3])
+    const d = Number(v4[4])
+    if (a > 255 || b > 255 || c > 255 || d > 255) return false
+    if (a === 127) return true // 127.0.0.0/8 loopback
+    if (a === 10) return true // 10.0.0.0/8 RFC1918
+    if (a === 192 && b === 168) return true // 192.168.0.0/16 RFC1918
+    if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12 RFC1918
+    if (a === 169 && b === 254) return true // 169.254.0.0/16 link-local + AWS metadata
+    if (a === 0) return true // 0.0.0.0/8 this-network
+    if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 CGNAT
+    if (a >= 224 && a <= 239) return true // 224.0.0.0/4 multicast
+    if (a >= 240) return true // 240.0.0.0/4 reserved + broadcast
+    return false
+  }
+
+  if (h.includes(':')) {
+    const lower = h.toLowerCase()
+    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true
+    if (lower === '::' || lower === '0:0:0:0:0:0:0:0') return true
+    if (/^f[cd][0-9a-f]{0,2}:/.test(lower)) return true // fc00::/7
+    if (/^fe[89ab][0-9a-f]?:/.test(lower)) return true // fe80::/10
+    if (/^ff[0-9a-f]{0,2}:/.test(lower)) return true // ff00::/8 multicast
+
+    let mappedTail: string | null = null
+    if (lower.startsWith('::ffff:')) mappedTail = lower.slice(7)
+    else if (lower.startsWith('0:0:0:0:0:ffff:')) mappedTail = lower.slice(15)
+    if (mappedTail !== null) {
+      if (mappedTail.includes('.')) return isPrivateHost(mappedTail)
+      const dotted = hexTailToDottedQuad(mappedTail)
+      if (dotted) return isPrivateHost(dotted)
+      return false
+    }
+
+    if (lower.startsWith('::') && lower.includes('.')) {
+      const tail = lower.slice(2)
+      if (/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(tail)) return isPrivateHost(tail)
+    }
+
+    if (lower.startsWith('2002:')) {
+      const m = /^2002:([0-9a-f]{1,4}):([0-9a-f]{1,4})(?::|$)/.exec(lower)
+      if (m) {
+        const dotted = hexTailToDottedQuad(`${m[1]}:${m[2]}`)
+        if (dotted) return isPrivateHost(dotted)
+      }
+    }
+
+    if (lower.startsWith('64:ff9b:') || lower.startsWith('0064:ff9b:')) {
+      const tail = lower.startsWith('0064:') ? lower.slice(10) : lower.slice(8)
+      if (tail.includes('.')) {
+        const v4match = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(tail)
+        if (v4match?.[1] !== undefined) return isPrivateHost(v4match[1])
+      }
+      const groups = tail.split(':').filter((g) => g.length > 0)
+      if (groups.length >= 2) {
+        const dotted = hexTailToDottedQuad(`${groups[groups.length - 2]}:${groups[groups.length - 1]}`)
+        if (dotted) return isPrivateHost(dotted)
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+/**
+ * Throw-on-reject URL guard. Use from any strategy whose backend may
+ * return adversarial / compromised URLs. `caller` is a short label
+ * ('multipart.signPart', 'post.intent', etc.) included in error messages
+ * so logs name the source.
+ */
+export function validateUploadUrl(
+  rawUrl: string,
+  caller: string,
+  opts: { allowedHosts?: string[]; allowPrivateHosts?: boolean } = {},
+): void {
+  if (typeof rawUrl !== 'string' || rawUrl.length === 0) {
+    throw new Error(`${caller} returned an invalid URL (empty or non-string)`)
+  }
+
+  // Cap raw URL length. Real presigned URLs are well under 4 KB; anything
+  // larger is either a server bug or an attacker probing the parser.
+  if (rawUrl.length > 8192) {
+    throw new Error(`${caller} URL exceeds 8192-byte length cap`)
+  }
+
+  if (rawUrl.includes('..')) {
+    throw new Error(`${caller} URL contains forbidden ".." segment`)
+  }
+
+  let parsed: URL
+  try {
+    parsed = new URL(rawUrl)
+  } catch {
+    throw new Error(`${caller} returned a malformed URL`)
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`${caller} URL has forbidden protocol "${parsed.protocol}"`)
+  }
+
+  if (opts.allowedHosts && opts.allowedHosts.length > 0) {
+    const host = parsed.host.toLowerCase()
+    const list = opts.allowedHosts.map((h) => h.toLowerCase())
+    if (!list.includes(host)) {
+      throw new Error(`${caller} URL host is not in the configured allow-list`)
+    }
+  }
+
+  if (!opts.allowPrivateHosts) {
+    if (isPrivateHost(parsed.hostname)) {
+      throw new Error(`${caller} URL points to a private/loopback host`)
+    }
+  }
+}

package/src/react/__tests__/use-dropzone.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'vitest'
+import { fileMatchesAccept, matchesAcceptToken, selectFiles } from '../use-dropzone'
+
+function f(name: string, type = ''): File {
+  return new File(['x'], name, { type })
+}
+
+describe('matchesAcceptToken', () => {
+  test('extension token (case-insensitive)', () => {
+    expect(matchesAcceptToken(f('photo.PNG'), '.png')).toBe(true)
+    expect(matchesAcceptToken(f('doc.pdf'), '.png')).toBe(false)
+  })
+
+  test('exact MIME token', () => {
+    expect(matchesAcceptToken(f('a', 'image/png'), 'image/png')).toBe(true)
+    expect(matchesAcceptToken(f('a', 'image/jpeg'), 'image/png')).toBe(false)
+  })
+
+  test('MIME wildcard token', () => {
+    expect(matchesAcceptToken(f('a', 'image/jpeg'), 'image/*')).toBe(true)
+    expect(matchesAcceptToken(f('a', 'video/mp4'), 'image/*')).toBe(false)
+  })
+
+  test('empty/whitespace token never matches', () => {
+    expect(matchesAcceptToken(f('a', 'image/png'), '   ')).toBe(false)
+  })
+})
+
+describe('fileMatchesAccept', () => {
+  test('absent or empty accept passes everything', () => {
+    expect(fileMatchesAccept(f('a', 'application/zip'))).toBe(true)
+    expect(fileMatchesAccept(f('a', 'application/zip'), '')).toBe(true)
+    expect(fileMatchesAccept(f('a', 'application/zip'), ' , ')).toBe(true)
+  })
+
+  test('matches when any token matches', () => {
+    expect(fileMatchesAccept(f('a.pdf', 'application/pdf'), 'image/*,.pdf')).toBe(true)
+    expect(fileMatchesAccept(f('a.png', 'image/png'), 'image/*,.pdf')).toBe(true)
+    expect(fileMatchesAccept(f('a.txt', 'text/plain'), 'image/*,.pdf')).toBe(false)
+  })
+})
+
+describe('selectFiles', () => {
+  const files = [f('a.png', 'image/png'), f('b.txt', 'text/plain'), f('c.jpg', 'image/jpeg')]
+
+  test('filters by accept', () => {
+    const out = selectFiles(files, { accept: 'image/*' })
+    expect(out.map((x) => x.name)).toEqual(['a.png', 'c.jpg'])
+  })
+
+  test('collapses to one when multiple is false', () => {
+    const out = selectFiles(files, { accept: 'image/*', multiple: false })
+    expect(out.map((x) => x.name)).toEqual(['a.png'])
+  })
+
+  test('keeps all when multiple omitted (defaults to many)', () => {
+    const out = selectFiles(files, {})
+    expect(out).toHaveLength(3)
+  })
+
+  test('empty when nothing matches', () => {
+    expect(selectFiles(files, { accept: 'video/*' })).toEqual([])
+  })
+})

package/src/react/index.ts

@@ -1,2 +1,5 @@
-export * from './upload-provider'
-export * from './use-uploader'
+export { isUploadStore, UploadProvider, useUploadStore } from './upload-provider'
+export type { Uploader } from './uploader.types'
+export type { UseDropzoneOptions, UseDropzoneReturn } from './use-dropzone'
+export { fileMatchesAccept, matchesAcceptToken, selectFiles, useDropzone } from './use-dropzone'
+export { createUploadFactory, useUploader, useUploaderActions } from './use-uploader'

package/src/react/upload-provider.tsx

@@ -1,121 +1,85 @@
-'use client'
+import { createContext, useContext, useEffect } from 'react'
+import type { Contracts } from '../core'
+import type { Store } from '../core/engine/store'
+import type { Uploader } from './uploader.types'
 
-/**
- * @fileoverview React context provider for the upload store.
- *
- * Provides the upload store instance to all child components via React Context.
- * This allows components to access the store without prop drilling.
- *
- * @module upload-provider
- */
-
-import { createContext, type ReactNode, useContext } from 'react'
-import { type CursorMap, type IntentMap, isRecord, type UploadResultBase } from '../core'
-import type { UploadStore } from '../core/engine/store'
-
-/**
- * React context for the upload store.
- * Initialized as null and must be provided via UploadProvider.
- *
- * Note: Context cannot be generic at the type level in React, so we use a base type.
- * The useUploadStore hook provides type safety through type assertion which is safe
- * because the provider ensures the correct type is stored.
- */
-const UploadContext = createContext<unknown | null>(null)
+const UploadContext = createContext<Store.UploadStore<any, any, any, any> | null>(null)
 
 /**
- * Provider component that makes the upload store available to child components.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @param props - Provider props
- * @param props.store - Upload store instance to provide
- * @param props.children - Child components that can access the store
+ * Context provider that distributes the upload store across the React component hierarchy.
  *
- * @returns {JSX.Element} Context provider wrapping children
+ * Wrap this provider around the top of your layout to enable child hooks like `useUploader`
+ * to access upload status.
  *
  * @example
  * ```tsx
- * <UploadProvider store={store}>
- *   <UploadDropzone purpose="avatar" />
- * </UploadProvider>
+ * const store = createUploadStore({ ... });
+ *
+ * function App() {
+ *   return (
+ *     <UploadProvider store={store}>
+ *       <UploadForm />
+ *     </UploadProvider>
+ *   );
+ * }
  * ```
+ * @author wildduck2 <https://github.com/wildduck2>
  */
 export function UploadProvider<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->({ store, children }: { store: UploadStore<M, C, P, R>; children: ReactNode }): React.JSX.Element {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>({ store, children }: Uploader.ProviderProps<M, C, P, R>) {
+  // Safe cleanup: destroy the store runner instance if the provider is unmounted.
+  useEffect(() => {
+    return () => {
+      if ('destroy' in store && typeof store.destroy === 'function') {
+        ;(store as unknown as { destroy: () => void }).destroy()
+      }
+    }
+  }, [store])
+
   return <UploadContext.Provider value={store}>{children}</UploadContext.Provider>
 }
 
 /**
- * Hook to access the upload store from React context when present.
- *
- * Some higher-level hooks support either an explicit store argument or context.
- * They use this helper so the context read stays unconditional without throwing
- * when a caller intentionally passes a store instance.
+ * Returns the active upload store instance from context.
+ * Throws a runtime exception if called outside an `<UploadProvider>`.
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export function useOptionalUploadStore<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+export function useUploadStore<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(): UploadStore<M, C, P, R> | null {
-  const store = useContext(UploadContext)
-  if (store === null) {
-    return null
-  }
-
-  if (!isUploadStore<M, C, P, R>(store)) {
-    throw new Error('UploadProvider received an invalid store value')
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(): Store.UploadStore<M, C, P, R> {
+  const context = useContext(UploadContext)
+  if (!context) {
+    throw new Error('useUploadStore must be used within an <UploadProvider>')
   }
-
-  return store
+  return context as Store.UploadStore<M, C, P, R>
 }
 
 /**
- * Hook to access the upload store from React context.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @returns {UploadStore<M, C, P>} The upload store instance
- * @throws {Error} If called outside of UploadProvider
- *
- * @example
- * ```tsx
- * const store = useUploadStore()
- * const snapshot = store.getSnapshot()
- * ```
+ * Runtime type guard: returns `true` when `value` exposes the upload-store
+ * surface (`getSnapshot`, `subscribe`, `dispatch`, `on`, `off`, `waitFor`).
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export function useUploadStore<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+export function isUploadStore<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(): UploadStore<M, C, P, R> {
-  const store = useOptionalUploadStore<M, C, P, R>()
-  if (!store) {
-    throw new Error('useUploadStore must be used within UploadProvider')
-  }
-  return store
-}
-
-function isUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  value: unknown,
-): value is UploadStore<M, C, P, R> {
-  if (!isRecord(value)) return false
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(value: unknown): value is Store.UploadStore<M, C, P, R> {
+  if (typeof value !== 'object' || value === null) return false
+  const val = value as Record<string, unknown>
   return (
-    typeof value.getSnapshot === 'function' &&
-    typeof value.subscribe === 'function' &&
-    typeof value.dispatch === 'function' &&
-    typeof value.on === 'function' &&
-    typeof value.off === 'function' &&
-    typeof value.waitFor === 'function'
+    typeof val['getSnapshot'] === 'function' &&
+    typeof val['subscribe'] === 'function' &&
+    typeof val['dispatch'] === 'function' &&
+    typeof val['on'] === 'function' &&
+    typeof val['off'] === 'function' &&
+    typeof val['waitFor'] === 'function'
   )
 }

package/src/react/uploader.types.ts

@@ -0,0 +1,80 @@
+import type React from 'react'
+import type { Contracts, Engine } from '../core'
+import type { Store } from '../core/engine/store'
+
+/**
+ * Public typings and namespaces consumed by React hook components.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace Uploader {
+  /**
+   * Return state payload returned by the `useUploader` hook.
+   *
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  export type State<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = Pick<Store.UploadStore<M, C, P, R>, 'dispatch' | 'on' | 'off'> & {
+    /** List of all registered upload items currently tracked. */
+    items: Array<Engine.Item<M, C, P, R>>
+
+    /** Upload items grouped by phase. */
+    byPhase: Record<Engine.Phase, Array<Engine.Item<M, C, P, R>>>
+
+    /** Subset of items currently active in the transfer phase. */
+    uploading: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items currently paused. */
+    paused: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items that successfully completed uploading and backend finalization. */
+    completed: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items currently in the error state. */
+    failed: Array<Engine.Item<M, C, P, R>>
+
+    /** Subset of items validated and waiting to begin uploading. */
+    ready: Array<Engine.Item<M, C, P, R>>
+  }
+
+  /**
+   * Bound action callbacks returned by context hooks.
+   *
+   * Houses both the bound dispatchers and the raw underlying store reference.
+   *
+   * @template M - Intent map type
+   * @template C - Cursor map type
+   * @template P - Purpose string union type
+   * @template R - Backend result shape
+   */
+  export type IActions<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = Pick<Store.UploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
+    /** The raw upload store instance. */
+    store: Store.UploadStore<M, C, P, R>
+  }
+
+  /**
+   * Props for the `<UploadProvider>` component.
+   */
+  export interface ProviderProps<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > {
+    /** The upload store instance to distribute. */
+    store: Store.UploadStore<M, C, P, R>
+    /** React child elements. */
+    children: React.ReactNode
+  }
+}