@gentleduck/upload 0.2.5 → 0.3.0

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)
+  })
+})

package/src/strategies/multipart/index.ts

@@ -1,53 +1,138 @@
 /**
- * Multipart strategy implementation (S3/MinIO style).
- * Signs each part on demand (signPart), uploads via PUT, then completes with ETags.
+ * S3/MinIO-style multipart strategy: sign each part on demand via `signPart`,
+ * PUT, then finalize with `completeMultipart` using collected ETags. Resumable
+ * persists ETags in the cursor and skips already-completed sessions.
  */
 
-import type { CursorMap, IntentMap, UploadResultBase, UploadStrategy } from '../../core/contracts'
-import { sleep } from '../../core/utils/async'
+import type { Contracts } from '../../core'
+import { UploadEngineError } from '../../core'
+import { validateUploadUrl } from '../../core/utils/url-safety'
+import { withRetry } from '../_shared/retry'
 
 const DEFAULT_MAX_PART_CONCURRENCY = 4
 
-export type MultipartIntent = {
-  strategy: 'multipart'
-  fileId: string
-  uploadId: string
-  partSize: number
-  partCount: number
-
-  // Optional legacy mode: backend might provide all urls up front
-  parts?: Array<{
-    partNumber: number
-    url: string
-    headers?: Record<string, string>
-  }>
-}
+/**
+ * Namespace containing types and interfaces specific to the S3/MinIO multipart upload strategy.
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
+export namespace MultipartStrategy {
+  /**
+   * Configuration options for the multipart upload strategy.
+   */
+  export type Config = {
+    /** Maximum concurrent HTTP PUT part uploads. Defaults to 4. */
+    maxPartConcurrency?: number
+    /**
+     * Optional case-insensitive list of trusted hosts (with optional port, e.g. `upload.example.com`).
+     * When specified, every signed part URL must match one of the listed hosts.
+     */
+    allowedHosts?: string[]
+    /**
+     * When `true`, allows private network IP addresses (loopback, link-local, RFC1918) in signed part URLs.
+     * Defaults to `false`.
+     */
+    allowPrivateHosts?: boolean
+  }
 
-export type MultipartCursor = {
-  done: Array<{
-    partNumber: number
-    etag: string
-    size: number
-  }>
+  /**
+   * Intent payload detailing part sizing and active upload session IDs returned by backends.
+   */
+  export type Intent = {
+    /** Discriminant matching strategy configuration registry keys. */
+    strategy: 'multipart'
+    /** Unique database identifier for the file resource. */
+    fileId: string
+    /** Active multipart session ID returned by S3/GCS. */
+    uploadId: string
+    /** Chunk size in bytes for each part slice (typically 5MB minimum). */
+    partSize: number
+    /** Total count of parts predicted for this file size. */
+    partCount: number
+
+    /** Optional array of pre-generated URLs and headers for each part (if signed up front). */
+    parts?: Array<{
+      partNumber: number
+      url: string
+      headers?: Record<string, string>
+    }>
+  }
 
   /**
-   * Marks that the multipart session was completed on the backend (parts assembled).
-   * This prevents re-sending completeMultipart on resume.
+   * Persisted resume state for multipart strategy uploads.
    */
-  completed?: true
+  export type Cursor = {
+    /** List of completed parts. */
+    done: Array<{
+      partNumber: number
+      etag: string
+      size: number
+    }>
+
+    /**
+     * True if the backend assembled the parts.
+     * Prevents repeating completeMultipart calls on subsequent resume attempts.
+     */
+    completed?: true
+  }
 }
 
-function isAbort(err: unknown) {
-  return err instanceof Error && (err.name === 'AbortError' || /abort/i.test(err.message))
+let warnedMissingAllowedHosts = false
+
+/**
+ * Reset internal warn-once latches. Test-only.
+ *
+ * @internal
+ */
+export function __resetMultipartWarningsForTests(): void {
+  warnedMissingAllowedHosts = false
+}
+
+/**
+ * Validate the per-part URL returned by `signPart` before it reaches the
+ * transport. Delegates to the shared {@link validateUploadUrl} SSRF guard and
+ * warns once when no `allowedHosts` are configured. Throws on rejection.
+ *
+ * @internal
+ */
+export function validatePartUrl(
+  rawUrl: string,
+  opts: { allowedHosts?: string[]; allowPrivateHosts?: boolean } = {},
+): void {
+  if ((!opts.allowedHosts || opts.allowedHosts.length === 0) && !warnedMissingAllowedHosts) {
+    warnedMissingAllowedHosts = true
+    console.warn(
+      '[duck-upload] multipartStrategy: no `allowedHosts` configured. Signed part URLs will be host-unrestricted. ' +
+        'Set MultipartStrategy.Config.allowedHosts to lock the upload host.',
+    )
+  }
+  validateUploadUrl(rawUrl, 'multipart.signPart', opts)
 }
 
+// types moved to MultipartStrategy namespace above
+
+/**
+ * S3/GCS-compatible Resumable Multipart Upload Strategy.
+ *
+ * Slices files into chunks, uploads them concurrently using S3 PUT requests,
+ * and completes the upload on the backend once all chunks are transferred.
+ *
+ * @example
+ * ```ts
+ * const registry = createStrategyRegistry([
+ *   multipartStrategy({ maxPartConcurrency: 4 })
+ * ]);
+ * ```
+ * @author wildduck2 <https://github.com/wildduck2>
+ */
 export function multipartStrategy<
-  M extends IntentMap & { multipart: MultipartIntent },
-  C extends CursorMap<M> & { multipart?: MultipartCursor },
+  M extends Contracts.Intent.Map & { multipart: MultipartStrategy.Intent },
+  C extends Contracts.Cursor.Map<M> & { multipart?: MultipartStrategy.Cursor },
   P extends string = string,
-  R extends UploadResultBase = UploadResultBase,
->(opts?: { maxPartConcurrency?: number }): UploadStrategy<M, C, P, R, 'multipart'> {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(opts?: MultipartStrategy.Config): Contracts.Strategy.Me<M, C, P, R, 'multipart'> {
   const maxPartConcurrency = Math.max(1, opts?.maxPartConcurrency ?? DEFAULT_MAX_PART_CONCURRENCY)
+  const allowedHosts = opts?.allowedHosts ?? []
+  const allowPrivateHosts = opts?.allowPrivateHosts === true
 
   return {
     id: 'multipart',
@@ -58,21 +143,19 @@ export function multipartStrategy<
       const totalBytes = ctx.file.size
       const partSize = Math.max(1, intent.partSize)
 
-      // Trust backend partCount if provided (important for maxParts rules)
+      // Trust backend `partCount` when provided  S3-style backends enforce a maxParts rule.
       const totalParts = Math.max(1, intent.partCount ?? Math.ceil(totalBytes / partSize))
 
-      // Restore cursor
       const cursor = ctx.readCursor()
       const done = new Map<number, { etag: string; size: number }>()
       if (cursor?.done) {
         for (const p of cursor.done) done.set(p.partNumber, { etag: p.etag, size: p.size })
       }
 
-      // If we already completed the multipart session in a previous run, do not re-complete.
-      // (The store will still run its generic finalization step.)
+      // Skip re-completing if a previous run already finalized the multipart
+      // session. The store still runs its generic finalization step.
       const alreadyCompleted = cursor?.completed === true
 
-      // Progress
       const inflightBytes = new Map<number, number>()
       let finishedBytes = 0
       for (const v of done.values()) finishedBytes += v.size
@@ -83,7 +166,6 @@ export function multipartStrategy<
         ctx.reportProgress({ uploadedBytes: finishedBytes + inflight, totalBytes })
       }
 
-      // Build queue
       const partsToUpload: Array<{ partNumber: number; start: number; end: number }> = []
       for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
         if (done.has(partNumber)) continue
@@ -102,90 +184,88 @@ export function multipartStrategy<
       const running = new Set<Promise<void>>()
 
       const getSignedPart = async (partNumber: number) => {
-        // Legacy fast path: intent.parts provided
+        // Fast path: backend pre-signed all parts in `intent.parts`.
         const fromIntent = intent.parts?.find((x) => x.partNumber === partNumber)
         if (fromIntent) return fromIntent
 
-        // Normal path: ask backend for this part url
         if (!ctx.api.multipart?.signPart) {
-          throw new Error(
-            'multipart.signPart is missing in UploadApi. Implement it to call your backend sign-part endpoint.',
-          )
+          throw new UploadEngineError('validation_failed', {
+            message:
+              'multipart.signPart is missing in UploadApi. Implement it to call your backend sign-part endpoint.',
+          })
         }
 
         const out = await ctx.api.multipart.signPart(
-          { fileId: intent.fileId, uploadId: intent.uploadId, partNumber },
-          { signal: ctx.signal },
+          { fileId: intent.fileId, uploadId: intent.uploadId, partNumber, attempt: ctx.attempt },
+          {
+            localId: ctx.localId,
+            purpose: ctx.purpose,
+            file: ctx.file,
+            intent: ctx.intent,
+            signal: ctx.signal,
+            fingerprint: ctx.fingerprint,
+            attempt: ctx.attempt,
+            createdAt: ctx.createdAt,
+            steps: ctx.steps,
+            meta: ctx.meta,
+            lastError: ctx.lastError,
+          },
         )
 
         return { partNumber, url: out.url, headers: out.headers }
       }
 
-      const uploadOne = async (
-        p: { partNumber: number; start: number; end: number },
-        retryCount = 0,
-      ): Promise<void> => {
-        const maxRetries = 3
-        try {
-          const blob = ctx.file.slice(p.start, p.end)
-          const size = blob.size
-
-          const signed = await getSignedPart(p.partNumber)
-
-          const res = await ctx.transport.put({
-            url: signed.url,
-            body: blob,
-            headers: signed.headers,
-            signal: ctx.signal,
-            onProgress: (loaded) => {
-              inflightBytes.set(p.partNumber, loaded)
+      const uploadOne = (p: { partNumber: number; start: number; end: number }): Promise<void> =>
+        withRetry(
+          async () => {
+            try {
+              const blob = ctx.file.slice(p.start, p.end)
+              const size = blob.size
+
+              const signed = await getSignedPart(p.partNumber)
+
+              validatePartUrl(signed.url, { allowedHosts, allowPrivateHosts })
+
+              const res = await ctx.transport.put({
+                url: signed.url,
+                body: blob,
+                headers: signed.headers ?? {},
+                signal: ctx.signal,
+                onProgress: (loaded) => {
+                  inflightBytes.set(p.partNumber, loaded)
+                  report()
+                },
+              })
+
+              inflightBytes.delete(p.partNumber)
+
+              const etag = res.etag
+              if (!etag) {
+                throw new UploadEngineError('upload_failed', {
+                  message:
+                    'Missing ETag from upload part response. Ensure MinIO/S3 CORS exposes ETag (Access-Control-Expose-Headers: ETag).',
+                })
+              }
+
+              finishedBytes += size
+              done.set(p.partNumber, { etag, size })
+
+              const snapshot: MultipartStrategy.Cursor = {
+                done: Array.from(done.entries())
+                  .map(([partNumber, v]) => ({ partNumber, etag: v.etag, size: v.size }))
+                  .sort((a, b) => a.partNumber - b.partNumber),
+              }
+              ctx.persistCursor(snapshot as C['multipart'])
               report()
-            },
-          })
-
-          inflightBytes.delete(p.partNumber)
-
-          const etag = res.etag
-          if (!etag) {
-            throw new Error(
-              'Missing ETag from upload part response. Ensure MinIO/S3 CORS exposes ETag (Access-Control-Expose-Headers: ETag).',
-            )
-          }
-
-          finishedBytes += size
-          done.set(p.partNumber, { etag, size })
-
-          const snapshot: MultipartCursor = {
-            done: Array.from(done.entries())
-              .map(([partNumber, v]) => ({ partNumber, etag: v.etag, size: v.size }))
-              .sort((a, b) => a.partNumber - b.partNumber),
-          }
-          ctx.persistCursor(snapshot as C['multipart'])
-          report()
-        } catch (err) {
-          inflightBytes.delete(p.partNumber)
-
-          if (ctx.signal?.aborted || isAbort(err)) throw err
-
-          // basic retry for network-ish failures
-          if (retryCount < maxRetries) {
-            const msg = err instanceof Error ? err.message : String(err)
-            const retryable =
-              /network/i.test(msg) ||
-              /timeout/i.test(msg) ||
-              /5\d\d/.test(msg) ||
-              /ECONNRESET/i.test(msg) ||
-              /EHOSTUNREACH/i.test(msg)
-
-            if (retryable) {
-              await sleep(2 ** retryCount * 500)
-              return uploadOne(p, retryCount + 1)
+            } catch (err) {
+              // Clear this part's in-flight bytes before retry/rethrow so the
+              // progress total does not double-count a re-attempted part.
+              inflightBytes.delete(p.partNumber)
+              throw err
             }
-          }
-
-          throw err
-        }
-      }
+          },
+          { signal: ctx.signal },
+        )
 
       while (queue.length > 0 || running.size > 0) {
         while (queue.length > 0 && running.size < maxPartConcurrency) {
@@ -211,9 +291,10 @@ export function multipartStrategy<
       async function completeMultipart() {
         if (alreadyCompleted) return
         if (!ctx.api.multipart?.completeMultipart) {
-          throw new Error(
-            'multipart.completeMultipart is missing in UploadApi. Implement it to call your backend complete endpoint.',
-          )
+          throw new UploadEngineError('validation_failed', {
+            message:
+              'multipart.completeMultipart is missing in UploadApi. Implement it to call your backend complete endpoint.',
+          })
         }
 
         const parts = Array.from(done.entries())
@@ -221,16 +302,30 @@ export function multipartStrategy<
           .sort((a, b) => a.partNumber - b.partNumber)
 
         if (parts.length !== totalParts) {
-          throw new Error(`Cannot complete multipart: expected ${totalParts} parts, got ${parts.length}`)
+          throw new UploadEngineError('complete_failed', {
+            message: `Cannot complete multipart: expected ${totalParts} parts, got ${parts.length}`,
+          })
         }
 
         await ctx.api.multipart.completeMultipart(
           { fileId: intent.fileId, uploadId: intent.uploadId, parts },
-          { signal: ctx.signal },
+          {
+            localId: ctx.localId,
+            purpose: ctx.purpose,
+            file: ctx.file,
+            intent: ctx.intent,
+            signal: ctx.signal,
+            fingerprint: ctx.fingerprint,
+            attempt: ctx.attempt,
+            createdAt: ctx.createdAt,
+            steps: ctx.steps,
+            meta: ctx.meta,
+            lastError: ctx.lastError,
+          },
         )
 
-        // Persist "completed" marker so resume doesn't re-complete.
-        const snapshot: MultipartCursor = {
+        // Persist `completed: true` so resume after this point does not re-call `completeMultipart`.
+        const snapshot: MultipartStrategy.Cursor = {
           done: Array.from(done.entries())
             .map(([partNumber, v]) => ({ partNumber, etag: v.etag, size: v.size }))
             .sort((a, b) => a.partNumber - b.partNumber),