@modern-admin/feature-upload 0.1.0

package/src/graphql.ts

@@ -0,0 +1,185 @@
+/**
+ * GraphQL extension for the upload feature — mirrors the REST upload
+ * controller (`POST /admin/api/resources/:id/actions/upload` and `DELETE`)
+ * with two mutations:
+ *
+ *   - `adminUpload(resourceId, field, file)` — upload a single file via the
+ *     `Upload` scalar (multipart/form-data per the GraphQL multipart spec).
+ *     Returns `UploadedFileInfo`.
+ *   - `adminCancelUpload(resourceId, field, key)` — cancel a still-pending
+ *     upload (file uploaded but record not yet saved). Returns `Boolean`.
+ *
+ * The extension is wired in the host application:
+ *   ```ts
+ *   ModernAdminGraphqlModule.forRoot({
+ *     extensions: [uploadGraphqlExtension()],
+ *   })
+ *   ```
+ *
+ * Authorisation re-uses the same `ModernAdmin.invoke()` access checks via
+ * `findResource(resourceId, currentAdmin)`.
+ *
+ * `@modern-admin/graphql` is an *optional peer dependency* of feature-upload —
+ * if you do not use the GraphQL transport you do not need to import this
+ * module at all.
+ */
+
+import {
+  GraphQLBoolean,
+  GraphQLNonNull,
+  GraphQLObjectType,
+  GraphQLString,
+  GraphQLInt,
+} from 'graphql'
+import {
+  type ExtensionContext,
+  type GraphqlSchemaExtension,
+  type GraphqlContext,
+} from '@modern-admin/graphql'
+import { ForbiddenError, ResourceNotFoundError } from '@modern-admin/core'
+import { UploadProviderRegistry } from './registry.js'
+import { PendingUploadsRegistry } from './pending-registry.js'
+import type { UploadedFileInfo } from './types.js'
+
+/** Default TTL for pending upload entries, mirrored from the controller. */
+const DEFAULT_PENDING_TTL_MS = 60 * 60 * 1000
+
+export interface UploadGraphqlExtensionOptions {
+  /**
+   * TTL applied when registering an uploaded key as pending. Mirrors the
+   * `pendingTtlMs` option on `ModernAdminUploadModule.forRoot()` — set both
+   * to the same value to keep REST and GraphQL behaviour identical.
+   */
+  pendingTtlMs?: number
+}
+
+export function uploadGraphqlExtension(
+  options: UploadGraphqlExtensionOptions = {},
+): (ctx: ExtensionContext) => GraphqlSchemaExtension {
+  const ttlMs = options.pendingTtlMs ?? DEFAULT_PENDING_TTL_MS
+  return ({ Upload }): GraphqlSchemaExtension => {
+    const UploadedFileInfoType = new GraphQLObjectType<UploadedFileInfo, GraphqlContext>({
+      name: 'UploadedFileInfo',
+      description: 'Metadata returned for one successfully uploaded file.',
+      fields: () => ({
+        key: { type: new GraphQLNonNull(GraphQLString) },
+        url: { type: new GraphQLNonNull(GraphQLString) },
+        name: { type: new GraphQLNonNull(GraphQLString) },
+        size: { type: new GraphQLNonNull(GraphQLInt) },
+        mimeType: { type: new GraphQLNonNull(GraphQLString) },
+      }),
+    })
+
+    return {
+      name: 'feature-upload',
+      types: [UploadedFileInfoType],
+      mutations: {
+        adminUpload: {
+          type: new GraphQLNonNull(UploadedFileInfoType),
+          description:
+            'Upload a single file for an upload-enabled property. Multi-file ' +
+            'properties accept one mutation invocation per file.',
+          args: {
+            resourceId: { type: new GraphQLNonNull(GraphQLString) },
+            field: { type: new GraphQLNonNull(GraphQLString) },
+            file: { type: new GraphQLNonNull(Upload) },
+          },
+          async resolve(_src, args, ctx) {
+            const { resourceId, field } = args as { resourceId: string; field: string }
+            const { providerId, registered } = resolveProperty(ctx, resourceId, field)
+            const upload = args.file as {
+              filename: string
+              mimeType: string
+              size: number
+              buffer: Buffer
+            }
+            const computedKey = registered.uploadPath
+              ? registered.uploadPath(upload.filename)
+              : undefined
+            const key = await registered.provider.upload(
+              {
+                originalName: upload.filename,
+                mimeType: upload.mimeType,
+                size: upload.size,
+                buffer: upload.buffer,
+              },
+              computedKey,
+            )
+            PendingUploadsRegistry.track(key, providerId, ttlMs)
+            const url = await registered.provider.getUrl(key)
+            const info: UploadedFileInfo = {
+              key,
+              url,
+              name: upload.filename,
+              size: upload.size,
+              mimeType: upload.mimeType,
+            }
+            return info
+          },
+        },
+        adminCancelUpload: {
+          type: new GraphQLNonNull(GraphQLBoolean),
+          description:
+            'Cancel a still-pending upload (file uploaded but record not yet ' +
+            'saved). Returns false when the key is no longer pending.',
+          args: {
+            resourceId: { type: new GraphQLNonNull(GraphQLString) },
+            field: { type: new GraphQLNonNull(GraphQLString) },
+            key: { type: new GraphQLNonNull(GraphQLString) },
+          },
+          async resolve(_src, args, ctx) {
+            const { resourceId, field, key } = args as {
+              resourceId: string
+              field: string
+              key: string
+            }
+            // Validate the resource/field exists & is upload-enabled. Mirrors
+            // the REST controller's check — prevents leaking arbitrary
+            // resource ids to authenticated clients.
+            resolveProperty(ctx, resourceId, field)
+            return PendingUploadsRegistry.cancel(key)
+          },
+        },
+      },
+    }
+  }
+}
+
+/**
+ * Resolve the resource + property and ensure it is wired to an upload
+ * provider. Mirrors the private helper in the REST upload controller — kept
+ * private to this module to avoid coupling. Throws GraphQL-friendly Error
+ * objects (not Nest exceptions) so they surface as standard GraphQL errors.
+ */
+function resolveProperty(
+  ctx: GraphqlContext,
+  resourceId: string,
+  field: string,
+): { providerId: string; registered: NonNullable<ReturnType<typeof UploadProviderRegistry.get>> } {
+  let resource
+  try {
+    resource = ctx.admin.findResource(resourceId)
+  } catch (err) {
+    if (err instanceof ResourceNotFoundError) throw new Error(err.message)
+    if (err instanceof ForbiddenError) throw new Error(err.message)
+    throw err
+  }
+  const decorator = resource.decorate()
+  const prop = decorator.getPropertyByKey(field)
+  if (!prop) {
+    throw new Error(`Property "${field}" not found on resource "${resourceId}"`)
+  }
+  const propJson = prop.toJSON()
+  const providerId = propJson.custom?.uploadProviderId as string | undefined
+  if (!providerId) {
+    throw new Error(
+      `Property "${field}" on resource "${resourceId}" is not configured for upload. ` +
+        'Apply uploadFeature() to the resource.',
+    )
+  }
+  const registered = UploadProviderRegistry.get(providerId)
+  if (!registered) {
+    throw new Error(`Upload provider "${providerId}" is not registered.`)
+  }
+  return { providerId, registered }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// @modern-admin/feature-upload — file upload plugin for modern-admin resources.
+//
+// Usage:
+//   import { uploadFeature, LocalUploadProvider, S3UploadProvider } from '@modern-admin/feature-upload'
+//   import { ModernAdminUploadModule } from '@modern-admin/feature-upload/nest'
+
+export { uploadFeature } from './upload-feature.js'
+export { UploadProviderRegistry } from './registry.js'
+export { PendingUploadsRegistry } from './pending-registry.js'
+
+// Built-in providers
+export { LocalUploadProvider, type LocalUploadOptions } from './providers/local.js'
+export { S3UploadProvider, type S3UploadOptions } from './providers/s3.js'
+
+// Types
+export type {
+  IUploadProvider,
+  UploadedFile,
+  UploadedFileInfo,
+  UploadFeatureOptions,
+  UploadPropertyConfig,
+} from './types.js'

package/src/nest/index.ts

@@ -0,0 +1,4 @@
+// @modern-admin/feature-upload/nest — NestJS module + controller for file uploads.
+
+export { ModernAdminUploadModule, type ModernAdminUploadModuleOptions } from './upload.module.js'
+export { UploadController } from './upload.controller.js'

package/src/nest/upload-sweeper.service.ts

@@ -0,0 +1,52 @@
+/**
+ * UploadSweeperService — periodic background task that purges expired entries
+ * from `PendingUploadsRegistry`.
+ *
+ * The interval starts when Nest calls `onModuleInit` and stops on
+ * `onModuleDestroy`. Set `sweepIntervalMs: 0` in the module options to
+ * disable scheduling (useful for tests that drive `sweep()` manually).
+ *
+ * TODO(roadmap): replace the in-process `setInterval` driver with a BullMQ
+ * (Redis-backed) job queue. Reasons:
+ *   - the registry will move to Redis in the multi-instance deployment story,
+ *     and the sweeper job belongs in the same place;
+ *   - BullMQ gives us cron scheduling, retries on transient storage errors,
+ *     visibility/metrics through Bull Board, and crash safety (a process
+ *     restart resumes scheduled sweeps instead of forgetting them);
+ *   - per-key cancel can become a delayed job (`removeJob` on confirm) which
+ *     is more efficient than a periodic full-table scan once we have many
+ *     pending entries.
+ * The migration should keep the same `PendingUploadsRegistry` API surface so
+ * call sites (controller, hooks) do not need to change — only the storage
+ * (Map → Redis) and the sweeper driver (setInterval → BullMQ Worker) flip.
+ */
+
+import { Inject, Injectable, type OnModuleDestroy, type OnModuleInit } from '@nestjs/common'
+import { PendingUploadsRegistry } from '../pending-registry.js'
+import { UPLOAD_MODULE_OPTIONS, type ModernAdminUploadModuleOptions } from './upload.tokens.js'
+
+const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000
+
+@Injectable()
+export class UploadSweeperService implements OnModuleInit, OnModuleDestroy {
+  private timer: ReturnType<typeof setInterval> | null = null
+
+  constructor(@Inject(UPLOAD_MODULE_OPTIONS) private readonly options: ModernAdminUploadModuleOptions) {}
+
+  onModuleInit(): void {
+    const interval = this.options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS
+    if (interval <= 0) return
+    this.timer = setInterval(() => {
+      void PendingUploadsRegistry.sweep()
+    }, interval)
+    // Allow the Node.js process to exit even if the timer is still scheduled.
+    if (typeof this.timer.unref === 'function') this.timer.unref()
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+  }
+}

package/src/nest/upload.controller.ts

@@ -0,0 +1,228 @@
+/**
+ * UploadController — handles file uploads for `type: 'file'` properties.
+ *
+ * Endpoints
+ * ---------
+ *   POST   /admin/api/resources/:resourceId/actions/upload?field=<propertyPath>
+ *     Content-Type: multipart/form-data
+ *     Accepts one or more files (any field names). Returns `UploadedFileInfo[]` —
+ *     callers writing to a single-value `'file'` property take the first item;
+ *     `isArray: true` properties consume the whole array.
+ *
+ *   DELETE /admin/api/resources/:resourceId/actions/upload?field=<path>&key=<key>
+ *     Cancels a still-pending upload (uploaded but not yet saved). Calls
+ *     `PendingUploadsRegistry.cancel(key)` which deletes the file from
+ *     storage. No-op (404) if the key is no longer pending — protects already
+ *     persisted files from being deleted via this endpoint.
+ *
+ * Authorisation re-uses `ModernAdminAuthGuard` from `@modern-admin/nest` —
+ * requires `ModernAdminModule.forRoot()` to be registered (globally or as a
+ * parent module).
+ */
+
+import {
+  BadRequestException,
+  Controller,
+  Delete,
+  ForbiddenException,
+  HttpCode,
+  Inject,
+  InternalServerErrorException,
+  NotFoundException,
+  Post,
+  Param,
+  Query,
+  Req,
+  UseGuards,
+} from '@nestjs/common'
+import { ApiCookieAuth, ApiTags } from '@nestjs/swagger'
+import type { IncomingMessage } from 'node:http'
+import Busboy from 'busboy'
+import {
+  ForbiddenError,
+  ResourceNotFoundError,
+  type ModernAdmin,
+} from '@modern-admin/core'
+import { MODERN_ADMIN, ModernAdminAuthGuard } from '@modern-admin/nest'
+import { UploadProviderRegistry } from '../registry.js'
+import { PendingUploadsRegistry } from '../pending-registry.js'
+import { UPLOAD_MODULE_OPTIONS, type ModernAdminUploadModuleOptions } from './upload.tokens.js'
+import type { UploadedFile, UploadedFileInfo } from '../types.js'
+
+/** Reads every file from a multipart/form-data stream using busboy. */
+function parseAllFiles(req: IncomingMessage): Promise<UploadedFile[]> {
+  return new Promise((resolve, reject) => {
+    let bb: ReturnType<typeof Busboy>
+    try {
+      bb = Busboy({ headers: req.headers as Record<string, string> })
+    } catch {
+      reject(new BadRequestException('Request is not multipart/form-data'))
+      return
+    }
+
+    const files: UploadedFile[] = []
+    /** Number of streams that have started but not yet ended. */
+    let pending = 0
+    let finished = false
+    let settled = false
+    let firstError: unknown
+
+    const tryResolve = (): void => {
+      if (settled || !finished || pending > 0) return
+      settled = true
+      if (firstError) reject(firstError)
+      else if (files.length === 0) reject(new BadRequestException('No file found in request body'))
+      else resolve(files)
+    }
+
+    bb.on('file', (_fieldname, stream, info) => {
+      pending++
+      const chunks: Buffer[] = []
+      stream.on('data', (chunk: Buffer) => chunks.push(chunk))
+      stream.on('end', () => {
+        const buffer = Buffer.concat(chunks)
+        files.push({
+          originalName: info.filename || 'upload',
+          mimeType: info.mimeType || 'application/octet-stream',
+          size: buffer.length,
+          buffer,
+        })
+        pending--
+        tryResolve()
+      })
+      stream.on('error', (err) => {
+        firstError = firstError ?? err
+        pending--
+        tryResolve()
+      })
+    })
+
+    bb.on('finish', () => {
+      finished = true
+      tryResolve()
+    })
+
+    bb.on('error', (err: unknown) => {
+      firstError = firstError ?? err
+      finished = true
+      tryResolve()
+    })
+
+    req.pipe(bb)
+  })
+}
+
+@ApiTags('Admin / Uploads')
+@ApiCookieAuth('session')
+@Controller('admin/api/resources/:resourceId/actions')
+@UseGuards(ModernAdminAuthGuard)
+export class UploadController {
+  constructor(
+    @Inject(MODERN_ADMIN) private readonly admin: ModernAdmin,
+    @Inject(UPLOAD_MODULE_OPTIONS) private readonly moduleOptions: ModernAdminUploadModuleOptions,
+  ) {}
+
+  /**
+   * Upload one or more files for a specific resource property.
+   *
+   * @param resourceId  Admin resource id (e.g. `'users'`)
+   * @param field       Property path (e.g. `'avatar'` / `'gallery'`)
+   * @param req         Raw Express / Node.js `IncomingMessage`
+   */
+  @Post('upload')
+  async upload(
+    @Param('resourceId') resourceId: string,
+    @Query('field') field: string,
+    @Req() req: IncomingMessage,
+  ): Promise<UploadedFileInfo[]> {
+    const { providerId, registered } = this.resolveProperty(resourceId, field)
+
+    // 1 — Parse the multipart body (collect every file).
+    const files = await parseAllFiles(req)
+
+    // 2 — If the property is single-value, only the first file is honoured.
+    //     The frontend sends one anyway; this is a safety bound.
+    const accepted = registered.isArray ? files : files.slice(0, 1)
+
+    // 3 — Upload each file, computing the storage key per-file so a custom
+    //     `uploadPath` generator can produce unique keys for each upload.
+    const ttlMs = this.moduleOptions.pendingTtlMs ?? 60 * 60 * 1000
+    const results: UploadedFileInfo[] = []
+    for (const file of accepted) {
+      const computedKey = registered.uploadPath ? registered.uploadPath(file.originalName) : undefined
+      const key = await registered.provider.upload(file, computedKey)
+      // Track as pending — it will be confirmed by `new.after`/`edit.after`
+      // when the form is saved, or cleaned up by the sweeper when the TTL
+      // expires (whichever comes first).
+      PendingUploadsRegistry.track(key, providerId, ttlMs)
+      const url = await registered.provider.getUrl(key)
+      results.push({ key, url, name: file.originalName, size: file.size, mimeType: file.mimeType })
+    }
+    return results
+  }
+
+  /**
+   * Cancel a still-pending upload — delete the file from storage immediately.
+   * Used by the editor when the user removes a file *before* saving the form.
+   *
+   * Returns 204 if the cancel succeeded, 404 if the key is not pending.
+   * The "not pending" branch protects already-persisted files: once a file
+   * has been confirmed via the action hooks it can no longer be removed via
+   * this endpoint — only via the regular edit/delete actions.
+   */
+  @Delete('upload')
+  @HttpCode(204)
+  async cancel(
+    @Param('resourceId') resourceId: string,
+    @Query('field') field: string,
+    @Query('key') key: string,
+  ): Promise<void> {
+    if (!key) throw new BadRequestException('Missing "key" query parameter')
+    // Validate that the resource/field is actually upload-enabled. This avoids
+    // leaking the existence of arbitrary resource ids to unauthenticated callers
+    // (the auth guard already requires authentication).
+    this.resolveProperty(resourceId, field)
+    const cancelled = await PendingUploadsRegistry.cancel(key)
+    if (!cancelled) {
+      throw new NotFoundException('Key is not pending — already saved or unknown')
+    }
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  /** Resolve the resource + property and ensure it is wired to an upload provider. */
+  private resolveProperty(
+    resourceId: string,
+    field: string,
+  ): { providerId: string; registered: NonNullable<ReturnType<typeof UploadProviderRegistry.get>> } {
+    let resource: ReturnType<typeof this.admin.findResource>
+    try {
+      resource = this.admin.findResource(resourceId)
+    } catch (err) {
+      if (err instanceof ResourceNotFoundError) throw new NotFoundException(err.message)
+      if (err instanceof ForbiddenError) throw new ForbiddenException(err.message)
+      throw err
+    }
+
+    const decorator = resource.decorate()
+    const prop = decorator.getPropertyByKey(field)
+    if (!prop) {
+      throw new NotFoundException(`Property "${field}" not found on resource "${resourceId}"`)
+    }
+
+    const propJson = prop.toJSON()
+    const providerId = propJson.custom?.uploadProviderId as string | undefined
+    if (!providerId) {
+      throw new BadRequestException(
+        `Property "${field}" on resource "${resourceId}" is not configured for upload. ` +
+          'Apply uploadFeature() to the resource.',
+      )
+    }
+
+    const registered = UploadProviderRegistry.get(providerId)
+    if (!registered) {
+      throw new InternalServerErrorException(`Upload provider "${providerId}" is not registered.`)
+    }
+    return { providerId, registered }
+  }
+}

package/src/nest/upload.module.ts

@@ -0,0 +1,44 @@
+/**
+ * ModernAdminUploadModule — registers `UploadController` plus the sweeper
+ * background task that purges orphaned pending uploads.
+ *
+ * Import alongside `ModernAdminModule.forRoot()` in the host application:
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     ModernAdminModule.forRoot({ global: true, ... }),
+ *     ModernAdminUploadModule.forRoot({ pendingTtlMs: 60 * 60 * 1000 }),
+ *     // feature modules that use uploadFeature() ...
+ *   ],
+ * })
+ * export class AdminModule {}
+ * ```
+ *
+ * The module depends on `MODERN_ADMIN` and `ModernAdminAuthGuard` being
+ * available in the DI tree, which is satisfied when `ModernAdminModule.forRoot`
+ * is registered with `global: true` (the recommended default).
+ */
+
+import { type DynamicModule, Module } from '@nestjs/common'
+import { UploadController } from './upload.controller.js'
+import { UploadSweeperService } from './upload-sweeper.service.js'
+import { UPLOAD_MODULE_OPTIONS, type ModernAdminUploadModuleOptions } from './upload.tokens.js'
+
+export type { ModernAdminUploadModuleOptions } from './upload.tokens.js'
+
+@Module({})
+export class ModernAdminUploadModule {
+  static forRoot(options: ModernAdminUploadModuleOptions = {}): DynamicModule {
+    return {
+      module: ModernAdminUploadModule,
+      global: options.global ?? false,
+      controllers: [UploadController],
+      providers: [
+        { provide: UPLOAD_MODULE_OPTIONS, useValue: options },
+        UploadSweeperService,
+      ],
+      exports: [UPLOAD_MODULE_OPTIONS],
+    }
+  }
+}

package/src/nest/upload.tokens.ts

@@ -0,0 +1,24 @@
+/**
+ * DI tokens + option types shared between `ModernAdminUploadModule`,
+ * `UploadController`, and the sweeper service.
+ */
+
+export const UPLOAD_MODULE_OPTIONS = Symbol.for('modern-admin.upload.module-options')
+
+export interface ModernAdminUploadModuleOptions {
+  /** Mark this module as global. Defaults to false. */
+  global?: boolean
+  /**
+   * TTL applied to freshly uploaded files before the sweeper deletes them.
+   * Default: 1 hour.  Files are confirmed (TTL becomes irrelevant) as soon
+   * as the parent record is saved, via the action hooks installed by
+   * `uploadFeature`.
+   */
+  pendingTtlMs?: number
+  /**
+   * Interval at which the sweeper runs. Default: 5 minutes.  Set to `0` to
+   * disable the periodic sweeper entirely (the registry still works — entries
+   * just never expire).
+   */
+  sweepIntervalMs?: number
+}

package/src/pending-registry.ts

@@ -0,0 +1,115 @@
+/**
+ * PendingUploadsRegistry — tracks files that were uploaded to storage but have
+ * not yet been "confirmed" by saving the parent record.
+ *
+ * Why
+ * ---
+ * Uploads happen *before* the form is submitted (the user picks a file, the
+ * editor calls `POST /upload`, gets back a key, stores it in form state). If
+ * the user then abandons the form (closes the tab, navigates away, server
+ * rejects the create payload, etc.), the file ends up orphaned in storage.
+ *
+ * How
+ * ---
+ * - The controller calls `track(key, providerId, ttlMs)` after every successful
+ *   upload, recording an expiry timestamp.
+ * - The action hooks installed by `uploadFeature` call `confirm(keys)` from
+ *   `new.after` / `edit.after` once the record is saved, removing the keys
+ *   from the pending set so they will not be swept.
+ * - The user-initiated `DELETE /upload?…` endpoint calls `cancel(key)` to
+ *   immediately remove the file from storage when the user removes a freshly
+ *   uploaded file *before* saving.
+ * - A periodic sweeper started by `ModernAdminUploadModule.forRoot()` calls
+ *   `sweep()` to delete files whose pending entry has expired. This handles
+ *   abandoned forms, browser crashes, and any other path that bypasses
+ *   client-side cleanup.
+ *
+ * The registry is a process-level singleton (same pattern as
+ * `UploadProviderRegistry`).
+ *
+ * TODO(roadmap): swap the in-process `Map` for a Redis-backed store and move
+ * the sweeper driver (`UploadSweeperService`) onto BullMQ. This is required
+ * for multi-instance deployments where one Nest replica serves the upload
+ * request and a different replica processes the form submission — without a
+ * shared store the second replica would not see the pending entry, the
+ * confirm hook would no-op, and the file would be swept on the originator.
+ * BullMQ also gives us crash-safe scheduling and retries.
+ */
+
+import { UploadProviderRegistry } from './registry.js'
+
+interface PendingEntry {
+  /** Provider id used to look up the upload provider for `delete()`. */
+  providerId: string
+  /** Epoch ms after which the entry is eligible for sweep. */
+  expiresAt: number
+}
+
+const _pending = new Map<string, PendingEntry>()
+
+export const PendingUploadsRegistry = {
+  /** Mark `key` as a freshly-uploaded, unconfirmed file. */
+  track(key: string, providerId: string, ttlMs: number): void {
+    _pending.set(key, { providerId, expiresAt: Date.now() + ttlMs })
+  },
+
+  /** Whether `key` is currently in the pending set (helper for tests / cancel). */
+  has(key: string): boolean {
+    return _pending.has(key)
+  },
+
+  /** Confirm one or more keys — they leave pending without being deleted. */
+  confirm(keys: ReadonlyArray<string>): void {
+    for (const k of keys) _pending.delete(k)
+  },
+
+  /**
+   * Cancel a single pending key — deletes the file from storage and removes
+   * the entry. No-op if the key is not pending (already confirmed or unknown).
+   */
+  async cancel(key: string): Promise<boolean> {
+    const entry = _pending.get(key)
+    if (!entry) return false
+    _pending.delete(key)
+    const cfg = UploadProviderRegistry.get(entry.providerId)
+    if (!cfg) return false
+    try {
+      await cfg.provider.delete(key)
+    } catch {
+      // Non-fatal — best-effort cleanup.
+    }
+    return true
+  },
+
+  /**
+   * Sweep expired entries — delete each from storage and from the registry.
+   * Returns the number of files swept.
+   */
+  async sweep(now: number = Date.now()): Promise<number> {
+    let swept = 0
+    for (const [key, entry] of _pending) {
+      if (entry.expiresAt <= now) {
+        _pending.delete(key)
+        const cfg = UploadProviderRegistry.get(entry.providerId)
+        if (!cfg) continue
+        try {
+          await cfg.provider.delete(key)
+          swept++
+        } catch {
+          // Non-fatal.
+        }
+      }
+    }
+    return swept
+  },
+
+  /** For test cleanup. */
+  clear(): void {
+    _pending.clear()
+  },
+
+  /** Number of currently-pending entries (for tests / introspection). */
+  size(): number {
+    return _pending.size
+  },
+}