@gentleduck/upload 0.2.6 → 0.3.0

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

@@ -0,0 +1,132 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { __resetPutWarningsForTests, type PutIntent, PutStrategy } from '../index'
+
+function makeCtx(url: string, overrides: Partial<PutIntent> = {}) {
+  const file = new File(['hello world'], 'a.txt', { type: 'text/plain' })
+  return {
+    intent: { strategy: 'put', fileId: 'f', url, ...overrides } satisfies PutIntent,
+    file,
+    signal: new AbortController().signal,
+    reportProgress: vi.fn(),
+    transport: {
+      put: vi.fn(async () => ({ etag: 'abc', headers: {} })),
+    },
+  }
+}
+
+describe('PutStrategy SSRF guard', () => {
+  beforeEach(() => {
+    __resetPutWarningsForTests()
+  })
+
+  test('rejects file://', async () => {
+    const s = PutStrategy()
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('file:///etc/passwd') as any)).rejects.toThrow(/forbidden protocol/)
+  })
+
+  test('rejects javascript:', async () => {
+    const s = PutStrategy()
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('javascript:alert(1)') as any)).rejects.toThrow(/forbidden protocol/)
+  })
+
+  test('rejects loopback', async () => {
+    const s = PutStrategy()
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('https://127.0.0.1/up') as any)).rejects.toThrow(/private/)
+  })
+
+  test('rejects AWS metadata IPv4', async () => {
+    const s = PutStrategy()
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('https://169.254.169.254/up') as any)).rejects.toThrow(/private/)
+  })
+
+  test('rejects host outside allowedHosts', async () => {
+    const s = PutStrategy({ allowedHosts: ['up.example.com'] })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('https://evil.example.com/up') as any)).rejects.toThrow(/allow-list/)
+  })
+
+  test('accepts allowlisted host and PUTs the file body', async () => {
+    const s = PutStrategy({ allowedHosts: ['up.example.com'] })
+    const ctx = makeCtx('https://up.example.com/up', { headers: { 'Content-Type': 'text/plain' } })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).resolves.toBeUndefined()
+    expect(ctx.transport.put).toHaveBeenCalledTimes(1)
+    const arg = (ctx.transport.put.mock.calls[0] as unknown as [{ url: string; body: unknown; headers: unknown }])[0]
+    expect(arg.url).toBe('https://up.example.com/up')
+    expect(arg.body).toBe(ctx.file)
+    expect(arg.headers).toEqual({ 'Content-Type': 'text/plain' })
+  })
+
+  test('allowPrivateHosts lets loopback through (opt-in)', async () => {
+    const s = PutStrategy({ allowPrivateHosts: true })
+    const ctx = makeCtx('https://127.0.0.1/up')
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).resolves.toBeUndefined()
+  })
+
+  test('warns once when allowedHosts not set', async () => {
+    const s = PutStrategy()
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+      await s.start(makeCtx('https://up.example.com/up') as any).catch(() => {})
+      // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+      await s.start(makeCtx('https://up.example.com/up') as any).catch(() => {})
+      expect(warn).toHaveBeenCalledTimes(1)
+    } finally {
+      warn.mockRestore()
+    }
+  })
+
+  test('caller label is "put.intent"', async () => {
+    const s = PutStrategy()
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(makeCtx('file:///etc/passwd') as any)).rejects.toThrow(/put\.intent/)
+  })
+
+  test('throws when intent has no url', async () => {
+    const s = PutStrategy()
+    const ctx = makeCtx('https://up.example.com/up')
+    // biome-ignore lint/suspicious/noExplicitAny: intentionally clearing the url
+    ;(ctx.intent as any).url = ''
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).rejects.toThrow(/missing url/)
+  })
+})
+
+describe('PutStrategy retry', () => {
+  beforeEach(() => {
+    __resetPutWarningsForTests()
+  })
+
+  test('retries a transient failure then succeeds', async () => {
+    const s = PutStrategy({ allowedHosts: ['up.example.com'], maxRetries: 2 })
+    const ctx = makeCtx('https://up.example.com/up')
+    let calls = 0
+    ctx.transport.put = vi.fn(async () => {
+      calls++
+      if (calls < 2) throw new Error('network error')
+      return { etag: 'ok', headers: {} }
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).resolves.toBeUndefined()
+    expect(calls).toBe(2)
+  })
+
+  test('does not retry a non-transient failure', async () => {
+    const s = PutStrategy({ allowedHosts: ['up.example.com'] })
+    const ctx = makeCtx('https://up.example.com/up')
+    let calls = 0
+    ctx.transport.put = vi.fn(async () => {
+      calls++
+      throw new Error('Upload failed with status 403')
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx shape is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).rejects.toThrow(/403/)
+    expect(calls).toBe(1)
+  })
+})

package/src/strategies/put/index.ts

@@ -0,0 +1,139 @@
+import type { Contracts } from '../../core'
+import { UploadEngineError } from '../../core'
+import { validateUploadUrl } from '../../core/utils/url-safety'
+import { withRetry } from '../_shared/retry'
+
+/**
+ * Types for the single-request presigned HTTP PUT upload strategy.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace PutStrategy {
+  /**
+   * Presigned HTTP PUT strategy configuration options.
+   */
+  export type Config = {
+    /**
+     * Case-insensitive allow-list of host names (with optional port). When
+     * set, the presigned PUT URL must match a listed host or it is rejected.
+     */
+    allowedHosts?: string[]
+    /**
+     * When `true`, allow private-network IP literals in the PUT URL.
+     * Defaults to `false`.
+     */
+    allowPrivateHosts?: boolean
+    /**
+     * Retries after the first attempt for transient network failures.
+     * Defaults to the shared retry default (3).
+     */
+    maxRetries?: number
+  }
+
+  /**
+   * Presigned HTTP PUT intent payload. The whole file body is sent in one
+   * request to a backend-signed URL (e.g. S3 `putObject`, GCS signed PUT).
+   */
+  export type Intent = {
+    /** Discriminant identifier matching strategy configuration registry keys. */
+    strategy: 'put'
+    /** Unique database identifier for the file resource. */
+    fileId: string
+    /** Presigned PUT destination URL. */
+    url: string
+    /** Optional request headers required by the signature (e.g. `Content-Type`). */
+    headers?: Record<string, string>
+    /** Optional epoch string indicating when the pre-signed credentials lapse. */
+    expiresAt?: string
+  }
+
+  /**
+   * Direct strategy cursor state representing that no resumable bytes exist.
+   */
+  export type Cursor = Record<string, never>
+}
+
+/** Convenience alias for {@link PutStrategy.Intent}. */
+export type PutIntent = PutStrategy.Intent
+
+let warnedMissingAllowedHosts = false
+
+/**
+ * Reset the warn-once latch. Test-only.
+ * @internal
+ */
+export function __resetPutWarningsForTests(): void {
+  warnedMissingAllowedHosts = false
+}
+
+/**
+ * Presigned single-request HTTP PUT strategy.
+ *
+ * Sends the entire file as the request body to a backend-signed URL in one PUT.
+ * The most common direct-to-storage pattern (S3 `putObject`, GCS/Azure signed
+ * PUT). Not resumable — use {@link multipartStrategy} or the tus strategy for
+ * resumable transfers.
+ *
+ * Security: the presigned URL is backend-supplied and flows straight to the
+ * transport, so a compromised backend or MITM could return a `file:`,
+ * `javascript:`, or private-network URL. Every URL is checked with
+ * {@link validateUploadUrl}; set {@link PutStrategy.Config.allowedHosts} to
+ * lock it to known hosts, or leave `allowPrivateHosts` at its default `false`
+ * to block loopback/private addresses.
+ *
+ * @example
+ * ```ts
+ * const strategies = createStrategyRegistry([
+ *   PutStrategy({ allowedHosts: ['uploads.example.com'] }),
+ *   multipartStrategy(),
+ * ]);
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function PutStrategy<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(opts: PutStrategy.Config = {}): Contracts.Strategy.Me<M, C, P, R, 'put'> {
+  const allowedHosts = opts.allowedHosts ?? []
+  const allowPrivateHosts = opts.allowPrivateHosts === true
+
+  return {
+    id: 'put',
+    resumable: false,
+
+    async start(ctx) {
+      const intent = ctx.intent as unknown as PutStrategy.Intent
+
+      if (!intent.url) {
+        throw new UploadEngineError('validation_failed', { message: 'put.start: intent missing url' })
+      }
+
+      if (allowedHosts.length === 0 && !warnedMissingAllowedHosts) {
+        warnedMissingAllowedHosts = true
+        console.warn(
+          '[duck-upload] PutStrategy: no `allowedHosts` configured. Presigned PUT URLs will be host-unrestricted. ' +
+            'Set PutStrategy.Config.allowedHosts to lock the upload host.',
+        )
+      }
+
+      validateUploadUrl(intent.url, 'put.intent', { allowedHosts, allowPrivateHosts })
+
+      const totalBytes = ctx.file.size
+
+      await withRetry(
+        () =>
+          ctx.transport.put({
+            url: intent.url,
+            body: ctx.file,
+            headers: intent.headers ?? {},
+            signal: ctx.signal,
+            onProgress(uploadedBytes, total) {
+              ctx.reportProgress({ uploadedBytes, totalBytes: total || totalBytes })
+            },
+          }),
+        { signal: ctx.signal, ...(opts.maxRetries !== undefined ? { maxRetries: opts.maxRetries } : {}) },
+      )
+    },
+  }
+}

package/src/strategies/registry/index.ts

@@ -4,17 +4,20 @@
  * Core strategy types live in `core/contracts/strategy.types.ts`.
  */
 
-import type { CursorMap, IntentMap, StrategyRegistry, UploadResultBase, UploadStrategy } from '../../core/contracts'
-
-export type { StrategyCtx, StrategyRegistry, UploadStrategy } from '../../core/contracts'
+import type { Contracts } from '../../core/contracts'
 
+/**
+ * Create an empty strategy registry. Register upload strategies with `set`, then
+ * resolve them by id with `get` / `has`.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
 export function createStrategyRegistry<
-  M extends IntentMap,
-  C extends CursorMap<M>,
-  P extends string = string,
-  R extends UploadResultBase = UploadResultBase,
->(): StrategyRegistry<M, C, P, R> {
-  const map: Partial<{ [K in keyof M & string]: UploadStrategy<M, C, P, R, K> }> = {}
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(): Contracts.Strategy.Registry<M, C, P, R> {
+  const map: Partial<{ [K in keyof M & string]: Contracts.Strategy.Me<M, C, P, R, K> }> = {}
 
   return {
     get(id) {

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

@@ -0,0 +1,159 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { __resetTusWarningsForTests, type TusIntent, TusStrategy } from '../index'
+
+type CursorState = { offset: number } | undefined
+
+/**
+ * Build a fake strategy ctx backed by an in-memory tus server that tracks its
+ * own offset and grows it by the size of each accepted PATCH.
+ */
+function makeCtx(opts: {
+  fileBytes: number
+  url?: string
+  intentChunkSize?: number
+  cursor?: CursorState
+  headOffset?: number | null // null = HEAD omitted from transport
+  serverStartOffset?: number
+}) {
+  const { fileBytes, url = 'https://tus.example.com/files/abc', cursor, headOffset = 0, serverStartOffset = 0 } = opts
+
+  const file = new File([new Uint8Array(fileBytes)], 'a.bin')
+  let persisted: CursorState = cursor
+  let serverOffset = serverStartOffset
+
+  const patch = vi.fn(async (args: { headers?: Record<string, string>; body: Blob }) => {
+    const sent = Number(args.headers?.['Upload-Offset'] ?? args.headers?.['upload-offset'])
+    // Simulate the server accepting the chunk at the declared offset.
+    serverOffset = sent + args.body.size
+    return { headers: { 'upload-offset': String(serverOffset) } }
+  })
+
+  const transport: Record<string, unknown> = { patch }
+  if (headOffset !== null) {
+    transport['head'] = vi.fn(async () => ({
+      status: 200,
+      headers: { 'upload-offset': String(headOffset) },
+    }))
+  }
+
+  const intent: TusIntent = { strategy: 'tus', fileId: 'f', url }
+  if (opts.intentChunkSize) intent.chunkSize = opts.intentChunkSize
+
+  const ctx = {
+    intent,
+    file,
+    signal: new AbortController().signal,
+    reportProgress: vi.fn(),
+    readCursor: () => persisted,
+    persistCursor: (c: CursorState) => {
+      persisted = c
+    },
+    transport,
+    get persistedOffset() {
+      return persisted?.offset
+    },
+  }
+  return {
+    ctx,
+    patch,
+    get server() {
+      return serverOffset
+    },
+  }
+}
+
+describe('TusStrategy', () => {
+  beforeEach(() => {
+    __resetTusWarningsForTests()
+  })
+
+  test('uploads a file in chunks and completes', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'], chunkSize: 10 })
+    const { ctx, patch } = makeCtx({ fileBytes: 25, intentChunkSize: 10 })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).resolves.toBeUndefined()
+    // 25 bytes / 10 per chunk -> 3 PATCHes (10, 10, 5)
+    expect(patch).toHaveBeenCalledTimes(3)
+    const sizes = patch.mock.calls.map((c) => (c[0] as { body: Blob }).body.size)
+    expect(sizes).toEqual([10, 10, 5])
+    // biome-ignore lint/suspicious/noExplicitAny: reading test helper getter
+    expect((ctx as any).persistedOffset).toBe(25)
+  })
+
+  test('sends the tus protocol headers', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'] })
+    const { ctx, patch } = makeCtx({ fileBytes: 5, intentChunkSize: 10 })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await s.start(ctx as any)
+    const headers = (patch.mock.calls[0]?.[0] as { headers: Record<string, string> }).headers
+    expect(headers['Tus-Resumable']).toBe('1.0.0')
+    expect(headers['Upload-Offset']).toBe('0')
+    expect(headers['Content-Type']).toBe('application/offset+octet-stream')
+  })
+
+  test('resumes from the server HEAD offset, not the start', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'], chunkSize: 10 })
+    // Server already has 20 of 25 bytes.
+    const { ctx, patch } = makeCtx({
+      fileBytes: 25,
+      intentChunkSize: 10,
+      headOffset: 20,
+      serverStartOffset: 20,
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await s.start(ctx as any)
+    // Only the final 5 bytes remain -> one PATCH.
+    expect(patch).toHaveBeenCalledTimes(1)
+    expect((patch.mock.calls[0]?.[0] as { body: Blob }).body.size).toBe(5)
+    const startHeader = (patch.mock.calls[0]?.[0] as { headers: Record<string, string> }).headers['Upload-Offset']
+    expect(startHeader).toBe('20')
+  })
+
+  test('falls back to the persisted cursor when no HEAD transport', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'], chunkSize: 10 })
+    const { ctx, patch } = makeCtx({
+      fileBytes: 25,
+      intentChunkSize: 10,
+      headOffset: null, // no head() on transport
+      cursor: { offset: 20 },
+      serverStartOffset: 20,
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await s.start(ctx as any)
+    expect(patch).toHaveBeenCalledTimes(1)
+    expect((patch.mock.calls[0]?.[0] as { body: Blob }).body.size).toBe(5)
+  })
+
+  test('is a no-op when already fully uploaded', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'] })
+    const { ctx, patch } = makeCtx({ fileBytes: 25, headOffset: 25, serverStartOffset: 25 })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await s.start(ctx as any)
+    expect(patch).not.toHaveBeenCalled()
+  })
+
+  test('rejects a non-allowlisted host', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'] })
+    const { ctx } = makeCtx({ fileBytes: 5, url: 'https://evil.example.com/f' })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).rejects.toThrow(/allow-list/)
+  })
+
+  test('rejects file:// URL', async () => {
+    const s = TusStrategy()
+    const { ctx } = makeCtx({ fileBytes: 5, url: 'file:///etc/passwd' })
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).rejects.toThrow(/forbidden protocol/)
+  })
+
+  test('bails when the server never advances the offset', async () => {
+    const s = TusStrategy({ allowedHosts: ['tus.example.com'], chunkSize: 10 })
+    const { ctx } = makeCtx({ fileBytes: 25, intentChunkSize: 10 })
+    // Server that always reports offset 0 -> no forward progress.
+    ;(ctx.transport as { patch: unknown }).patch = vi.fn(async () => ({
+      headers: { 'upload-offset': '0' },
+    }))
+    // biome-ignore lint/suspicious/noExplicitAny: test ctx is a subset of the full strategy ctx
+    await expect(s.start(ctx as any)).rejects.toThrow(/did not advance/)
+  })
+})

package/src/strategies/tus/index.ts

@@ -0,0 +1,211 @@
+/**
+ * tus resumable upload strategy (creation-less).
+ *
+ * The backend intent hands back a ready tus upload URL (creation is done
+ * server-side), so this strategy implements only the transfer half of the
+ * protocol: HEAD to read the server's `Upload-Offset`, then a sequence of
+ * `PATCH` requests with `application/offset+octet-stream` bodies. The offset is
+ * persisted in the cursor so a resumed run continues where it left off, and
+ * re-confirmed against the server via HEAD when the transport supports it.
+ *
+ * @see https://tus.io/protocols/resumable-upload
+ */
+
+import type { Contracts } from '../../core'
+import { UploadEngineError } from '../../core'
+import { validateUploadUrl } from '../../core/utils/url-safety'
+import { withRetry } from '../_shared/retry'
+
+/** tus protocol version this strategy speaks. */
+const TUS_RESUMABLE = '1.0.0'
+
+/** Default PATCH chunk size when neither intent nor config specifies one: 8 MiB. */
+const DEFAULT_TUS_CHUNK_SIZE = 8 * 1024 * 1024
+
+/**
+ * Types for the tus resumable upload strategy.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace TusStrategy {
+  /**
+   * Configuration options for the tus strategy.
+   */
+  export type Config = {
+    /** PATCH chunk size in bytes. Overridden by `intent.chunkSize`. Defaults to 8 MiB. */
+    chunkSize?: number
+    /**
+     * Case-insensitive allow-list of host names (with optional port). When set,
+     * the tus upload URL must match a listed host or it is rejected.
+     */
+    allowedHosts?: string[]
+    /**
+     * When `true`, allow private-network IP literals in the tus URL.
+     * Defaults to `false`.
+     */
+    allowPrivateHosts?: boolean
+    /** Retries after the first attempt for transient PATCH/HEAD failures. Defaults to 3. */
+    maxRetries?: number
+  }
+
+  /**
+   * tus intent payload. The backend has already created the upload; `url` is the
+   * ready upload resource to PATCH against.
+   */
+  export type Intent = {
+    /** Discriminant matching strategy configuration registry keys. */
+    strategy: 'tus'
+    /** Unique database identifier for the file resource. */
+    fileId: string
+    /** Ready tus upload URL (backend-created via the creation extension). */
+    url: string
+    /** Optional per-upload chunk size override in bytes. */
+    chunkSize?: number
+    /** Optional extra headers to send on every request (e.g. auth). */
+    headers?: Record<string, string>
+  }
+
+  /**
+   * Persisted resume state: the last acknowledged upload offset in bytes.
+   */
+  export type Cursor = {
+    /** Byte offset already accepted by the server. */
+    offset: number
+  }
+}
+
+/** Convenience alias for {@link TusStrategy.Intent}. */
+export type TusIntent = TusStrategy.Intent
+
+let warnedMissingAllowedHosts = false
+
+/**
+ * Reset the warn-once latch. Test-only.
+ * @internal
+ */
+export function __resetTusWarningsForTests(): void {
+  warnedMissingAllowedHosts = false
+}
+
+/** Parse a non-negative integer header value, or `null` when absent/invalid. */
+function parseOffsetHeader(headers: Record<string, string> | undefined, name: string): number | null {
+  const raw = headers?.[name] ?? headers?.[name.toLowerCase()]
+  if (raw === undefined) return null
+  const n = Number(raw)
+  return Number.isInteger(n) && n >= 0 ? n : null
+}
+
+/**
+ * tus resumable upload strategy (creation-less).
+ *
+ * @example
+ * ```ts
+ * const registry = createStrategyRegistry([
+ *   TusStrategy({ allowedHosts: ['tus.example.com'], chunkSize: 8 * 1024 * 1024 }),
+ * ]);
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export function TusStrategy<
+  M extends Contracts.Intent.Map & { tus: TusStrategy.Intent },
+  C extends Contracts.Cursor.Map<M> & { tus?: TusStrategy.Cursor },
+  P extends string = string,
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(opts: TusStrategy.Config = {}): Contracts.Strategy.Me<M, C, P, R, 'tus'> {
+  const allowedHosts = opts.allowedHosts ?? []
+  const allowPrivateHosts = opts.allowPrivateHosts === true
+  const configChunkSize = opts.chunkSize
+  const retryOpts = opts.maxRetries !== undefined ? { maxRetries: opts.maxRetries } : {}
+
+  return {
+    id: 'tus',
+    resumable: true,
+
+    async start(ctx) {
+      const intent = ctx.intent
+      if (!intent.url) {
+        throw new UploadEngineError('validation_failed', { message: 'tus.start: intent missing url' })
+      }
+
+      if (allowedHosts.length === 0 && !warnedMissingAllowedHosts) {
+        warnedMissingAllowedHosts = true
+        console.warn(
+          '[duck-upload] TusStrategy: no `allowedHosts` configured. tus upload URLs will be host-unrestricted. ' +
+            'Set TusStrategy.Config.allowedHosts to lock the upload host.',
+        )
+      }
+
+      validateUploadUrl(intent.url, 'tus.intent', { allowedHosts, allowPrivateHosts })
+
+      const url = intent.url
+      const total = ctx.file.size
+      const chunkSize = Math.max(1, intent.chunkSize ?? configChunkSize ?? DEFAULT_TUS_CHUNK_SIZE)
+      const baseHeaders: Record<string, string> = { 'Tus-Resumable': TUS_RESUMABLE, ...(intent.headers ?? {}) }
+
+      // Start from the persisted offset, then confirm against the server when
+      // the transport can HEAD (server offset is authoritative on resume).
+      let offset = ctx.readCursor()?.offset ?? 0
+
+      if (ctx.transport.head) {
+        const head = ctx.transport.head
+        try {
+          const res = await withRetry(() => head({ url, headers: baseHeaders, signal: ctx.signal }), {
+            signal: ctx.signal,
+            ...retryOpts,
+          })
+          const serverOffset = parseOffsetHeader(res.headers, 'upload-offset')
+          if (serverOffset !== null) offset = serverOffset
+        } catch (err) {
+          // Abort must propagate; other HEAD failures fall back to the cursor
+          // offset and let the first PATCH surface a real error.
+          if (ctx.signal?.aborted || (err instanceof Error && err.name === 'AbortError')) throw err
+        }
+      }
+
+      // Clamp a stale/oversized persisted offset back into range.
+      if (offset > total) offset = total
+
+      ctx.reportProgress({ uploadedBytes: offset, totalBytes: total })
+
+      while (offset < total) {
+        if (ctx.signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+
+        const start = offset
+        const end = Math.min(total, start + chunkSize)
+        const chunk = ctx.file.slice(start, end)
+
+        const res = await withRetry(
+          () =>
+            ctx.transport.patch({
+              url,
+              body: chunk,
+              headers: {
+                ...baseHeaders,
+                'Upload-Offset': String(start),
+                'Content-Type': 'application/offset+octet-stream',
+              },
+              signal: ctx.signal,
+              onProgress: (loaded) => {
+                ctx.reportProgress({ uploadedBytes: start + loaded, totalBytes: total })
+              },
+            }),
+          { signal: ctx.signal, ...retryOpts },
+        )
+
+        // Trust the server's acknowledged offset; fall back to the local end.
+        const acked = parseOffsetHeader(res.headers, 'upload-offset')
+        offset = acked !== null ? acked : end
+
+        if (offset <= start) {
+          // No forward progress -> a broken/misconfigured server. Bail rather
+          // than spin forever.
+          throw new UploadEngineError('upload_failed', {
+            message: `tus: server did not advance Upload-Offset (stuck at ${offset} of ${total}).`,
+          })
+        }
+
+        ctx.persistCursor({ offset } as C['tus'])
+        ctx.reportProgress({ uploadedBytes: offset, totalBytes: total })
+      }
+    },
+  }
+}

package/dist/async-DxRWu4le.js

@@ -1 +0,0 @@
-function e(e){return new Promise(t=>setTimeout(t,e))}export{e as t};