@gentleduck/upload 0.2.6 → 0.3.0

package/src/react/use-uploader.tsx

@@ -1,105 +1,90 @@
-'use client'
-
 import * as React from 'react'
-import type {
-  CursorMap,
-  IntentMap,
-  UploadCommand,
-  UploadEventMap,
-  UploadItem,
-  UploadPhase,
-  UploadResultBase,
-} from '../core'
-import type { UploadStore } from '../core/engine/store'
-import { useOptionalUploadStore, useUploadStore } from './upload-provider'
-
-export function createUploadFactory<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(store: UploadStore<M, C, P, R>) {
-  return () => useUploader<M, C, P, R>(store)
-}
-
-export type PickItemsByPhase<Phase extends UploadPhase> = Extract<
-  UploadItem<IntentMap, CursorMap<IntentMap>, string, UploadResultBase>,
-  { phase: Phase }
->
-
-type Uploader<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase> = {
-  items: UploadItem<M, C, P, R>[]
-  byPhase: Record<string, UploadItem<M, C, P, R>[]>
-  dispatch: (cmd: UploadCommand<P>) => void
-  on: <K extends keyof UploadEventMap<M, C, P, R> & string>(
-    type: K,
-    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
-  ) => () => void
-  off: <K extends keyof UploadEventMap<M, C, P, R> & string>(
-    type: K,
-    cb: (payload: UploadEventMap<M, C, P, R>[K]) => void,
-  ) => () => void
-  uploading: UploadItem<M, C, P, R>[]
-  paused: UploadItem<M, C, P, R>[]
-  completed: UploadItem<M, C, P, R>[]
-  failed: UploadItem<M, C, P, R>[]
-  ready: UploadItem<M, C, P, R>[]
-}
+import { useMemo, useSyncExternalStore } from 'react'
+import type { Contracts, Engine } from '../core'
+import type { Store } from '../core/engine/store'
+import { useUploadStore } from './upload-provider'
+import type { Uploader } from './uploader.types'
 
 /**
- * Imperative action surface. Declared explicitly (not inferred) so generated
- * .d.ts files do not leak internal generic names created by `store.on.bind(store)`.
+ * Hook to consume the upload store state, track files, and interact with the upload engine.
+ *
+ * Exposes files, categorizes items by status phase (ready, uploading, paused, completed, failed),
+ * and registers action dispatchers.
+ *
+ * Can optionally be passed a specific store instance directly. Otherwise, it will read the store from context.
+ *
+ * @example
+ * ```tsx
+ * function UploadForm() {
+ *   const { items, uploading, dispatch } = useUploader();
+ *
+ *   const onFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+ *     if (e.target.files) {
+ *       dispatch({ type: 'addFiles', files: Array.from(e.target.files), purpose: 'avatar' });
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={onFileChange} multiple />
+ *       <ul>
+ *         {items.map(item => (
+ *           <li key={item.localId}>{item.fingerprint.name} - {item.phase}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @template M - Intent map type
+ * @template C - Cursor map type
+ * @template P - Purpose string union type
+ * @template R - Backend result shape
+ * @author wildduck2 <https://github.com/wildduck2>
  */
-export type UploaderActions<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
-> = Pick<UploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
-  store: UploadStore<M, C, P, R>
-}
-
-export function useUploader<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(): Uploader<M, C, P, R>
-export function useUploader<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(store: UploadStore<M, C, P, R>): Uploader<M, C, P, R>
 export function useUploader<
-  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,
->(providedStore?: UploadStore<M, C, P, R> | undefined) {
-  const contextStore = useOptionalUploadStore<M, C, P, R>()
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(providedStore?: Store.UploadStore<M, C, P, R> | undefined): Uploader.State<M, C, P, R> {
+  const contextStore = useUploadStore<M, C, P, R>()
   const store = providedStore ?? contextStore
+
   if (!store) {
-    throw new Error('useUploader must be used within UploadProvider when no store argument is provided')
+    throw new Error('useUploader must be used within an <UploadProvider> or passed a store instance directly.')
   }
 
-  const snapshot = React.useSyncExternalStore(
-    store.subscribe.bind(store),
-    store.getSnapshot.bind(store),
-    store.getSnapshot.bind(store),
+  const state = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR fallback placeholder.
   )
 
-  const items = React.useMemo(() => {
-    return Array.from(snapshot.items.values())
-  }, [snapshot.items])
+  const items = useMemo(() => {
+    return Array.from(state.items.values())
+  }, [state])
 
-  const byPhase = React.useMemo(() => {
-    const result: Record<string, UploadItem<M, C, P, R>[]> = {}
+  const byPhase = useMemo(() => {
+    const result: Record<Engine.Phase, Array<Engine.Item<M, C, P, R>>> = {
+      validating: [],
+      creating_intent: [],
+      ready: [],
+      queued: [],
+      uploading: [],
+      paused: [],
+      completing: [],
+      completed: [],
+      error: [],
+      canceled: [],
+    }
     items.forEach((item) => {
-      if (!result[item.phase]) {
-        result[item.phase] = []
+      const phase = item.phase
+      if (!result[phase]) {
+        result[phase] = []
       }
-      result[item.phase].push(item)
+      result[phase].push(item)
     })
     return result
   }, [items])
@@ -118,12 +103,19 @@ export function useUploader<
   }
 }
 
+/**
+ * Returns the store's imperative actions (dispatch, event bindings) along with a direct
+ * reference to the store instance. Does not trigger React re-renders on upload progress or state changes.
+ *
+ * Use this when you only need to trigger commands or subscribe to events without binding UI lists.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
 export function useUploaderActions<
-  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,
->(): UploaderActions<M, C, P, R> {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(): Uploader.IActions<M, C, P, R> {
   const store = useUploadStore<M, C, P, R>()
 
   const dispatch = React.useMemo(() => store.dispatch.bind(store), [store])
@@ -131,3 +123,18 @@ export function useUploaderActions<
 
   return { dispatch, on, store }
 }
+
+/**
+ * Creates a bound `useUploader` hook pre-configured for a specific store instance.
+ *
+ * Useful for building static multi-uploader widgets or context-free setups.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function createUploadFactory<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(store: Store.UploadStore<M, C, P, R>) {
+  return () => useUploader<M, C, P, R>(store)
+}

package/src/strategies/_shared/__tests__/retry.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest'
+import { DEFAULT_MAX_RETRIES, isAbort, isRetryable, withRetry } from '../retry'
+
+describe('isAbort', () => {
+  it('detects AbortError by name', () => {
+    const err = new Error('cancelled')
+    err.name = 'AbortError'
+    expect(isAbort(err)).toBe(true)
+  })
+
+  it('detects abort by message', () => {
+    expect(isAbort(new Error('request was aborted'))).toBe(true)
+  })
+
+  it('is false for plain errors and non-errors', () => {
+    expect(isAbort(new Error('network down'))).toBe(false)
+    expect(isAbort('abort')).toBe(false)
+  })
+})
+
+describe('isRetryable', () => {
+  it('matches transient network wording and codes', () => {
+    expect(isRetryable(new Error('network error'))).toBe(true)
+    expect(isRetryable(new Error('socket timeout'))).toBe(true)
+    expect(isRetryable(new Error('Upload failed with status 503'))).toBe(true)
+    expect(isRetryable(new Error('read ECONNRESET'))).toBe(true)
+    expect(isRetryable(new Error('connect EHOSTUNREACH'))).toBe(true)
+  })
+
+  it('is false for non-transient errors', () => {
+    expect(isRetryable(new Error('validation failed'))).toBe(false)
+    expect(isRetryable(new Error('Upload failed with status 403'))).toBe(false)
+  })
+})
+
+describe('withRetry', () => {
+  it('returns first-attempt result without retrying', async () => {
+    const fn = vi.fn(async () => 'ok')
+    await expect(withRetry(fn)).resolves.toBe('ok')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries transient failures then succeeds', async () => {
+    let calls = 0
+    const fn = vi.fn(async () => {
+      calls++
+      if (calls < 3) throw new Error('network glitch')
+      return calls
+    })
+    await expect(withRetry(fn, { maxRetries: 5 })).resolves.toBe(3)
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('passes the zero-based attempt index to fn', async () => {
+    const seen: number[] = []
+    let calls = 0
+    await withRetry(
+      async (attempt) => {
+        seen.push(attempt)
+        calls++
+        if (calls < 3) throw new Error('timeout')
+        return null
+      },
+      { maxRetries: 5 },
+    )
+    expect(seen).toEqual([0, 1, 2])
+  })
+
+  it('gives up after maxRetries and rethrows', async () => {
+    const fn = vi.fn(async () => {
+      throw new Error('network down')
+    })
+    await expect(withRetry(fn, { maxRetries: 2 })).rejects.toThrow('network down')
+    // first attempt + 2 retries
+    expect(fn).toHaveBeenCalledTimes(3)
+  })
+
+  it('does not retry non-retryable errors', async () => {
+    const fn = vi.fn(async () => {
+      throw new Error('validation failed')
+    })
+    await expect(withRetry(fn)).rejects.toThrow('validation failed')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not retry aborts', async () => {
+    const err = new Error('aborted')
+    err.name = 'AbortError'
+    const fn = vi.fn(async () => {
+      throw err
+    })
+    await expect(withRetry(fn)).rejects.toThrow('aborted')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('stops immediately when the signal is already aborted', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const fn = vi.fn(async () => {
+      throw new Error('network down')
+    })
+    await expect(withRetry(fn, { signal: controller.signal })).rejects.toThrow('network down')
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('honors a custom retryable predicate', async () => {
+    let calls = 0
+    const fn = vi.fn(async () => {
+      calls++
+      if (calls < 2) throw new Error('please retry me')
+      return 'done'
+    })
+    await expect(withRetry(fn, { retryable: (e) => /retry me/.test(String(e)) })).resolves.toBe('done')
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+
+  it('exposes a sane default retry count', () => {
+    expect(DEFAULT_MAX_RETRIES).toBe(3)
+  })
+})

package/src/strategies/_shared/retry.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared retry helpers used by upload strategies.
+ *
+ * Centralizes the abort detection, transient-error classification, and
+ * exponential-backoff loop that `multipart` grew inline and that `post` and
+ * `tus` reuse.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+
+import { sleep } from '../../core/utils/async'
+
+/** Default number of retries (attempts after the first) for transient failures. */
+export const DEFAULT_MAX_RETRIES = 3
+
+/** Base backoff in ms; delay for retry `n` (0-indexed) is `2 ** n * BASE`. */
+const BACKOFF_BASE_MS = 500
+
+/**
+ * True when `err` represents an aborted request (either an `AbortError` or a
+ * message mentioning "abort"). Aborts are never retried.
+ */
+export function isAbort(err: unknown): boolean {
+  return err instanceof Error && (err.name === 'AbortError' || /abort/i.test(err.message))
+}
+
+/**
+ * Classify an error as a transient network failure worth retrying. Matches
+ * network/timeout wording, 5xx status codes, and common Node socket errnos.
+ */
+export function isRetryable(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err)
+  return (
+    /network/i.test(msg) ||
+    /timeout/i.test(msg) ||
+    /5\d\d/.test(msg) ||
+    /ECONNRESET/i.test(msg) ||
+    /EHOSTUNREACH/i.test(msg)
+  )
+}
+
+/** Options for {@link withRetry}. */
+export type WithRetryOptions = {
+  /** Retries after the first attempt. Defaults to {@link DEFAULT_MAX_RETRIES}. */
+  maxRetries?: number
+  /**
+   * Abort signal. When aborted (or the error is an abort) the loop stops
+   * immediately and rethrows without further retries.
+   */
+  signal?: AbortSignal
+  /**
+   * Custom retry predicate. Defaults to {@link isRetryable}. Aborts are always
+   * terminal regardless of this predicate.
+   */
+  retryable?: (err: unknown) => boolean
+}
+
+/**
+ * Run `fn` and retry transient failures with exponential backoff.
+ *
+ * Aborts (signal aborted, or an abort-shaped error) short-circuit and rethrow
+ * immediately. Non-retryable errors rethrow on first failure. `fn` receives the
+ * zero-based attempt index.
+ */
+export async function withRetry<T>(fn: (attempt: number) => Promise<T>, opts: WithRetryOptions = {}): Promise<T> {
+  const maxRetries = Math.max(0, opts.maxRetries ?? DEFAULT_MAX_RETRIES)
+  const retryable = opts.retryable ?? isRetryable
+
+  let attempt = 0
+  for (;;) {
+    try {
+      return await fn(attempt)
+    } catch (err) {
+      if (opts.signal?.aborted || isAbort(err)) throw err
+      if (attempt >= maxRetries || !retryable(err)) throw err
+      await sleep(2 ** attempt * BACKOFF_BASE_MS)
+      attempt++
+    }
+  }
+}

package/src/strategies/index.ts

@@ -1,15 +1,9 @@
-/**
- * @fileoverview Public exports for upload strategies.
- *
- * Re-exports all strategy implementations and types for convenient importing.
- *
- * Available strategies:
- * - PostStrategy: Simple POST uploads (presigned forms)
- * - multipartStrategy: Chunked multipart uploads (S3-style, resumable)
- *
- * @module upload-strategies
- */
-
-export * from './multipart'
-export * from './post'
-export * from './registry'
+export type { MultipartStrategy } from './multipart'
+export { multipartStrategy } from './multipart'
+export type { PostIntent } from './post'
+export { PostStrategy } from './post'
+export type { PutIntent } from './put'
+export { PutStrategy } from './put'
+export { createStrategyRegistry } from './registry'
+export type { TusIntent } from './tus'
+export { TusStrategy } from './tus'

package/src/strategies/multipart/__tests__/multipart.test.ts

@@ -0,0 +1,229 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import type { Transport } from '../../../core'
+import { __resetMultipartWarningsForTests, multipartStrategy, validatePartUrl } from '../index'
+
+describe('validatePartUrl', () => {
+  beforeEach(() => {
+    __resetMultipartWarningsForTests()
+  })
+
+  test('rejects file:// URL', () => {
+    expect(() => validatePartUrl('file:///etc/passwd')).toThrow(/forbidden protocol/)
+  })
+
+  test('rejects javascript: URL', () => {
+    expect(() => validatePartUrl('javascript:alert(1)')).toThrow(/forbidden protocol/)
+  })
+
+  test('rejects malformed URL', () => {
+    expect(() => validatePartUrl('not a url')).toThrow(/malformed/)
+  })
+
+  test('rejects empty URL', () => {
+    expect(() => validatePartUrl('')).toThrow(/invalid URL/)
+  })
+
+  test('rejects URL containing ".." segment', () => {
+    expect(() => validatePartUrl('https://upload.example.com/a/../b')).toThrow(/\.\./)
+  })
+
+  test('rejects http://127.0.0.1/upload when allowPrivateHosts is false', () => {
+    expect(() => validatePartUrl('http://127.0.0.1/upload')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects RFC1918 hosts (10/8, 172.16/12, 192.168/16)', () => {
+    expect(() => validatePartUrl('http://10.0.0.5/x')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://172.16.1.1/x')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://192.168.1.1/x')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects IPv6 loopback ::1 and link-local fe80::', () => {
+    expect(() => validatePartUrl('http://[::1]/x')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://[fe80::1]/x')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://[fc00::1]/x')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects IPv6 unspecified :: and multicast ff02::1', () => {
+    expect(() => validatePartUrl('http://[::]/x')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://[ff02::1]/x')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects IPv4-mapped IPv6 (dotted-quad, canonical hex, fully expanded)', () => {
+    expect(() => validatePartUrl('http://[::ffff:127.0.0.1]/')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://[::ffff:7f00:1]/')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://[0:0:0:0:0:ffff:7f00:1]/')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects 6to4 IPv6 carrying a private IPv4 (2002:7f00:1::)', () => {
+    expect(() => validatePartUrl('http://[2002:7f00:1::]/')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects NAT64 IPv6 carrying a private IPv4 (64:ff9b::7f00:1)', () => {
+    expect(() => validatePartUrl('http://[64:ff9b::7f00:1]/')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects AWS cloud-metadata 169.254.169.254', () => {
+    expect(() => validatePartUrl('http://169.254.169.254/latest/meta-data/')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects CGNAT 100.64.0.0/10', () => {
+    expect(() => validatePartUrl('http://100.64.5.5/')).toThrow(/private\/loopback/)
+  })
+
+  test('rejects multicast 224.0.0.0/4 and broadcast 255.255.255.255', () => {
+    expect(() => validatePartUrl('http://224.0.0.1/')).toThrow(/private\/loopback/)
+    expect(() => validatePartUrl('http://255.255.255.255/')).toThrow(/private\/loopback/)
+  })
+
+  test('accepts http://127.0.0.1/upload when allowPrivateHosts is true', () => {
+    expect(() => validatePartUrl('http://127.0.0.1/upload', { allowPrivateHosts: true })).not.toThrow()
+  })
+
+  test('accepts hardened private/embedded forms when allowPrivateHosts is true', () => {
+    const cases = [
+      'http://[::1]/',
+      'http://[::ffff:127.0.0.1]/',
+      'http://[::ffff:7f00:1]/',
+      'http://[2002:7f00:1::]/',
+      'http://[64:ff9b::7f00:1]/',
+      'http://169.254.169.254/latest/meta-data/',
+      'http://100.64.5.5/',
+      'http://224.0.0.1/',
+      'http://255.255.255.255/',
+      'http://[::]/',
+      'http://[ff02::1]/',
+    ]
+    for (const u of cases) {
+      expect(() => validatePartUrl(u, { allowPrivateHosts: true })).not.toThrow()
+    }
+  })
+
+  test('public URL still flows through (happy path)', () => {
+    expect(() =>
+      validatePartUrl('https://upload.example.com/parts/3', {
+        allowedHosts: ['upload.example.com'],
+      }),
+    ).not.toThrow()
+  })
+
+  test('allowedHosts: accepts listed host, rejects others', () => {
+    expect(() =>
+      validatePartUrl('https://upload.example.com/parts/3', {
+        allowedHosts: ['upload.example.com'],
+      }),
+    ).not.toThrow()
+
+    expect(() =>
+      validatePartUrl('https://evil.example.com/parts/3', {
+        allowedHosts: ['upload.example.com'],
+      }),
+    ).toThrow(/allow-list/)
+  })
+
+  test('allowedHosts matches case-insensitively and is port-aware', () => {
+    expect(() =>
+      validatePartUrl('https://Upload.Example.COM:8443/p', {
+        allowedHosts: ['upload.example.com:8443'],
+      }),
+    ).not.toThrow()
+
+    expect(() =>
+      validatePartUrl('https://upload.example.com:9000/p', {
+        allowedHosts: ['upload.example.com:8443'],
+      }),
+    ).toThrow(/allow-list/)
+  })
+
+  test('warns once on omitted allowedHosts, suppresses on subsequent calls', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      validatePartUrl('https://upload.example.com/a')
+      validatePartUrl('https://upload.example.com/b')
+      validatePartUrl('https://upload.example.com/c')
+      expect(spy).toHaveBeenCalledTimes(1)
+      expect(spy.mock.calls[0]?.[0]).toMatch(/allowedHosts/)
+    } finally {
+      spy.mockRestore()
+    }
+  })
+})
+
+describe('multipartStrategy  happy path', () => {
+  beforeEach(() => {
+    __resetMultipartWarningsForTests()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  function makeCtx(opts: { signPartUrl: string; fileSize?: number }) {
+    const size = opts.fileSize ?? 8
+    const file = new File([new Uint8Array(size)], 'a.bin')
+    const transport: Pick<Transport.Options, 'put' | 'postForm' | 'patch'> = {
+      put: vi.fn(async (_args: Parameters<Transport.Options['put']>[0]) => ({ etag: 'etag-1' })),
+      postForm: vi.fn(async () => ({})),
+      patch: vi.fn(async () => ({})),
+    }
+
+    const cursors: Array<unknown> = []
+    const ctx = {
+      file,
+      intent: {
+        strategy: 'multipart' as const,
+        fileId: 'f1',
+        uploadId: 'u1',
+        partSize: size, // one part
+        partCount: 1,
+      },
+      signal: new AbortController().signal,
+      transport: transport,
+      api: {
+        createIntent: vi.fn(),
+        complete: vi.fn(),
+        multipart: {
+          signPart: vi.fn(async () => ({ url: opts.signPartUrl, headers: undefined })),
+          completeMultipart: vi.fn(async () => undefined),
+        },
+      } as unknown as Parameters<ReturnType<typeof multipartStrategy>['start']>[0]['api'],
+      readCursor: () => undefined,
+      persistCursor: (c: unknown) => {
+        cursors.push(c)
+      },
+      reportProgress: () => {},
+    }
+    return { ctx, transport, cursors }
+  }
+
+  test('signed https://upload.example.com URL flows through to transport.put', async () => {
+    const { ctx, transport } = makeCtx({ signPartUrl: 'https://upload.example.com/parts/3' })
+    const start = multipartStrategy({ allowedHosts: ['upload.example.com'] })
+    await start.start(ctx as unknown as Parameters<typeof start.start>[0])
+    expect(transport.put).toHaveBeenCalledTimes(1)
+    const callArgs = (transport.put as ReturnType<typeof vi.fn>).mock.calls[0]?.[0] as { url: string }
+    expect(callArgs.url).toBe('https://upload.example.com/parts/3')
+  })
+
+  test('file:// signed URL is rejected before reaching transport.put', async () => {
+    const { ctx, transport } = makeCtx({ signPartUrl: 'file:///etc/passwd' })
+    const start = multipartStrategy({ allowedHosts: ['upload.example.com'] })
+    await expect(start.start(ctx as unknown as Parameters<typeof start.start>[0])).rejects.toThrow(/forbidden protocol/)
+    expect(transport.put).not.toHaveBeenCalled()
+  })
+
+  test('private-host signed URL is rejected when allowPrivateHosts is false', async () => {
+    const { ctx, transport } = makeCtx({ signPartUrl: 'http://127.0.0.1/upload' })
+    const start = multipartStrategy({})
+    // suppress the one-time warn
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    await expect(start.start(ctx as unknown as Parameters<typeof start.start>[0])).rejects.toThrow(/private\/loopback/)
+    expect(transport.put).not.toHaveBeenCalled()
+  })
+
+  test('private-host signed URL is accepted when allowPrivateHosts is true', async () => {
+    const { ctx, transport } = makeCtx({ signPartUrl: 'http://127.0.0.1/upload' })
+    const start = multipartStrategy({ allowPrivateHosts: true, allowedHosts: ['127.0.0.1'] })
+    await start.start(ctx as unknown as Parameters<typeof start.start>[0])
+    expect(transport.put).toHaveBeenCalledTimes(1)
+  })
+})