refactor(files): bound every archive extraction and trim the extractor's option surface

`maxMaterializedItems` was opt-in, so only the new unzip route bounded its output
tree — the copilot `materialize_file` and `POST /api/tools/file/manage` extract
paths had no cap on folder creation at all. An archive within MAX_ARCHIVE_ENTRIES
can still imply far more folders than files, so the cap now defaults to
MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS and applies to all three callers.

`materializedRootFolderCount` was a hand-maintained number that had to agree with
what an opaque callback would create, and the callee could not check it; drift
surfaced only as an over-limit archive slipping past the cap. It is now derived
from whether `prepareRootFolder` ran, so the contract is just "the callback
creates exactly one folder".

Also single-sources the ArchiveError -> HTTP status map (it was copied into both
the internal error policy and the tools route), drops IdempotencyService config
that only `executeWithIdempotency` reads (the extraction lease uses
atomicallyClaim/release, so no result is ever stored), hoists the duplicated
predicates in purgeCreatedWorkspaceFile and archiveWorkspaceFileFolderIfEmpty so
a lock and its write cannot diverge, and names UPLOAD_SESSION_LOCAL_PUT_MAX_BYTES
rather than overloading the multipart part size as the local single-PUT ceiling.

Adds coverage for the two guards nothing exercised: the re-validation of the
segments `prepareRootFolder` actually returned, and the default cap applying with
no caller opt-in.

UI: the drop overlay used --surface-4 unconditionally, which renders grey over the
light-mode canvas; matches the canonical overlay's --white/dark:--surface-4 and
swaps arbitrary px type sizes for named tokens.

Author: waleedlatif1

apps/sim/app/api/tools/file/manage/route.ts

@@ -34,6 +34,7 @@ import {
   type DecompressResult,
   decompressArchiveBufferToWorkspaceFiles,
   MAX_ARCHIVE_BYTES,
+  statusForArchiveError,
 } from '@/lib/uploads/archive'
 import type { getWorkspaceFile } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
 import {
@@ -1183,7 +1184,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           if (archiveError instanceof ArchiveError) {
             // The error message is single-sourced in ArchiveError (caps included);
             // only the HTTP status is mapped here.
-            const status = archiveError.reason === 'invalid' ? 400 : 413
+            const status = statusForArchiveError(archiveError)
             return NextResponse.json(
               { success: false, error: `"${archive.name}": ${archiveError.message}` },
               { status }

apps/sim/app/workspace/[workspaceId]/files/files.tsx

@@ -1440,7 +1440,7 @@ export function Files() {
         }
         const file = fileByIdRef.current.get(parsed.id)
         if (file && isArchiveFileName(file.name)) {
-          if (!extractFile.isPending) setExtractTargetId(file.id)
+          setExtractTargetId(file.id)
           return
         }
         router.push(
@@ -1450,7 +1450,7 @@ export function Files() {
         )
       }
     },
-    [router, workspaceId, currentFolderId, setFilesParams, extractFile.isPending]
+    [router, workspaceId, currentFolderId, setFilesParams]
   )
 
   const handleExtract = async () => {
@@ -1923,11 +1923,11 @@ export function Files() {
                 }
               />
               {isDraggingOver ? (
-                <div className='pointer-events-none absolute inset-0 z-[var(--z-dropdown)] flex flex-col items-center justify-center gap-2 border border-[var(--brand-secondary)] border-dashed bg-[var(--surface-4)] transition-colors'>
+                <div className='pointer-events-none absolute inset-0 z-[var(--z-dropdown)] flex flex-col items-center justify-center gap-2 border border-[var(--brand-secondary)] border-dashed bg-[var(--white)] transition-colors dark:bg-[var(--surface-4)]'>
                   <Upload className='size-5 text-[var(--brand-secondary)]' />
                   <div className='flex flex-col gap-0.5 text-center'>
-                    <p className='text-[14px] text-[var(--brand-secondary)]'>Drop to upload</p>
-                    <p className='text-[11px] text-[var(--text-tertiary)]'>
+                    <p className='text-[var(--brand-secondary)] text-sm'>Drop to upload</p>
+                    <p className='text-[var(--text-tertiary)] text-xs'>
                       Release files here to add them to this workspace
                     </p>
                   </div>

apps/sim/lib/uploads/archive.test.ts

@@ -59,6 +59,7 @@ import {
   MAX_ARCHIVE_CENTRAL_DIR_RECORDS,
   MAX_ARCHIVE_ENTRY_BYTES,
 } from '@/lib/uploads/archive'
+import { MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS } from '@/lib/workspace-files/limits'
 
 const TEST_PRINCIPAL = {
   kind: 'session',
@@ -651,7 +652,6 @@ describe('decompressArchiveBufferToWorkspaceFiles', () => {
         workspaceId: 'ws',
         principal: TEST_PRINCIPAL,
         prepareRootFolder,
-        materializedRootFolderCount: 1,
         maxMaterializedItems: 2,
       })
     ).rejects.toMatchObject({ name: 'ArchiveError', reason: 'too_many_entries' })
@@ -665,7 +665,6 @@ describe('decompressArchiveBufferToWorkspaceFiles', () => {
         workspaceId: 'ws',
         principal: TEST_PRINCIPAL,
         prepareRootFolder,
-        materializedRootFolderCount: 1,
         maxMaterializedItems: 3,
       })
     ).resolves.toMatchObject({ extracted: [expect.objectContaining({ name: 'file.txt' })] })
@@ -694,7 +693,6 @@ describe('decompressArchiveBufferToWorkspaceFiles', () => {
           workspaceId: 'ws',
           principal: TEST_PRINCIPAL,
           prepareRootFolder,
-          materializedRootFolderCount: 1,
           maxMaterializedItems: 5000,
         })
       ).rejects.toMatchObject({
@@ -736,6 +734,58 @@ describe('decompressArchiveBufferToWorkspaceFiles', () => {
     expect(mockUpload).not.toHaveBeenCalled()
   })
 
+  it('applies the workspace bulk limit by default, so every caller is bounded', async () => {
+    // 1000 files, each under six folders unique to it: 7000 materialized items from an entry
+    // count that is itself within MAX_ARCHIVE_ENTRIES. No caller opts in to this cap.
+    const entries: Record<string, string> = {}
+    for (let index = 0; index < 1000; index += 1) {
+      entries[`a${index}/b/c/d/e/f/file.txt`] = 'x'
+    }
+    const buffer = await buildZip(entries)
+
+    await expect(
+      decompressArchiveBufferToWorkspaceFiles(buffer, {
+        workspaceId: 'ws',
+        principal: TEST_PRINCIPAL,
+      })
+    ).rejects.toMatchObject({
+      name: 'ArchiveError',
+      reason: 'too_many_entries',
+      message: expect.stringContaining(`the maximum is ${MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS}`),
+    })
+
+    expect(mockEnsureFolder).not.toHaveBeenCalled()
+    expect(mockUpload).not.toHaveBeenCalled()
+  })
+
+  it('re-validates the segments prepareRootFolder actually returned, before any upload', async () => {
+    const buffer = await buildZip({ 'nested/file.txt': 'x' })
+    // A callback that validates one path and returns a different, invalid one. The callee
+    // cannot trust the callback to have checked what it returns, so it re-checks itself.
+    const prepareRootFolder = vi.fn(async (validate: (segments: string[]) => void) => {
+      validate(['bundle'])
+      return Array.from({ length: MAX_FOLDER_PATH_SEGMENTS + 1 }, (_, index) => `deep-${index}`)
+    })
+
+    await expect(
+      decompressArchiveBufferToWorkspaceFiles(buffer, {
+        workspaceId: 'ws',
+        principal: TEST_PRINCIPAL,
+        prepareRootFolder,
+      })
+    ).rejects.toMatchObject({
+      name: 'ArchiveError',
+      reason: 'invalid',
+      message: expect.stringContaining(
+        `Folder paths cannot exceed ${MAX_FOLDER_PATH_SEGMENTS} segments`
+      ),
+    })
+
+    expect(prepareRootFolder).toHaveBeenCalledOnce()
+    expect(mockEnsureFolder).not.toHaveBeenCalled()
+    expect(mockUpload).not.toHaveBeenCalled()
+  })
+
   it('throws ArchiveError invalid for a non-zip buffer (no files written)', async () => {
     await expect(
       decompressArchiveBufferToWorkspaceFiles(Buffer.from('not a zip at all'), {

apps/sim/lib/uploads/archive.ts

@@ -15,6 +15,7 @@ import type { WorkspaceFileSecretProvenance } from '@/lib/uploads/contexts/works
 import { getFileExtension, getMimeTypeFromExtension } from '@/lib/uploads/utils/file-utils'
 import { createWorkspaceFileFromBuffer } from '@/lib/workspace-files/application/create-workspace-file'
 import { ensureWorkspaceFileFolderPathOperation } from '@/lib/workspace-files/application/workspace-file-folders'
+import { MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS } from '@/lib/workspace-files/limits'
 import type { UserFile } from '@/executor/types'
 
 /**
@@ -87,6 +88,15 @@ export class ArchiveError extends Error {
   }
 }
 
+/**
+ * The caller-facing HTTP status for an {@link ArchiveError}. A malformed archive is the
+ * caller's request being wrong (400); every other reason is a cap the payload exceeded (413).
+ * Single-sourced beside the reason union so a new variant is classified in exactly one place.
+ */
+export function statusForArchiveError(error: ArchiveError): number {
+  return error.reason === 'invalid' ? 400 : 413
+}
+
 const MB = 1024 * 1024
 
 /**
@@ -264,13 +274,14 @@ function throwInflateCapError(reason: 'entry' | 'total', entryName: string): nev
  * When `prepareRootFolder` is provided it takes precedence over
  * `rootFolderSegments`: it runs once, only after the caps have been proven and
  * only when at least one safe entry exists, and extraction lands under the
- * segments it returns. Before inserting a deduplicated root, the callback must
- * pass its final segments to the supplied validator so the complete destination
- * path is rejected before any folder mutation. `materializedRootFolderCount`
- * must equal the number of folders that callback will create, so the
- * `maxMaterializedItems` pre-check (files + implied folders + root folders)
- * counts them and rejects an over-limit archive before the callback materializes
- * anything.
+ * segments it returns. It must create exactly one folder, and must pass its
+ * final segments to the supplied validator before inserting it so the complete
+ * destination path is rejected before any folder mutation. That one folder is
+ * counted by the `maxMaterializedItems` pre-check (files + implied folders +
+ * root folder), which rejects an over-limit archive before the callback
+ * materializes anything. That cap always applies — it defaults to
+ * {@link MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS} — because the file count alone
+ * does not bound folder creation.
  *
  * Filesystem-noise entries (`__MACOSX/`, `.DS_Store`, `Thumbs.db`) are extracted
  * verbatim unless `skipNoiseEntries` is set — the HTTP decompress route preserves
@@ -287,7 +298,6 @@ export async function decompressArchiveBufferToWorkspaceFiles(
     prepareRootFolder?: (
       validateRootFolderSegments: (rootFolderSegments: string[]) => void
     ) => Promise<string[]>
-    materializedRootFolderCount?: number
     maxMaterializedItems?: number
     skipNoiseEntries?: boolean
     secretProvenance?: WorkspaceFileSecretProvenance
@@ -299,8 +309,7 @@ export async function decompressArchiveBufferToWorkspaceFiles(
     principal,
     rootFolderSegments = [],
     prepareRootFolder,
-    materializedRootFolderCount = 0,
-    maxMaterializedItems,
+    maxMaterializedItems = MAX_WORKSPACE_FILE_BULK_AFFECTED_ITEMS,
     skipNoiseEntries = false,
     secretProvenance = { status: 'unknown' },
     notifyWorkspaceChange = true,
@@ -366,24 +375,29 @@ export async function decompressArchiveBufferToWorkspaceFiles(
   }
   validateRootFolderSegments(rootFolderSegments)
 
-  if (maxMaterializedItems !== undefined) {
-    const folderPaths = new Set<string>()
-    for (const { segments } of safeEntries) {
-      for (let depth = 1; depth < segments.length; depth += 1) {
-        folderPaths.add(segments.slice(0, depth).join('\0'))
-      }
-    }
-    const materializedItems =
-      safeEntries.length +
-      folderPaths.size +
-      (safeEntries.length > 0 ? materializedRootFolderCount : 0)
-    if (materializedItems > maxMaterializedItems) {
-      throw new ArchiveError(
-        'too_many_entries',
-        `Archive would create ${materializedItems} files and folders; the maximum is ${maxMaterializedItems}.`
-      )
+  const impliedFolderPaths = new Set<string>()
+  for (const { segments } of safeEntries) {
+    let prefix = ''
+    for (let depth = 0; depth < segments.length - 1; depth += 1) {
+      prefix += `\0${segments[depth]}`
+      impliedFolderPaths.add(prefix)
     }
   }
+  /**
+   * Bounds the whole output tree, not just the file count: 1000 entries nested 64 deep imply
+   * far more folders than files, and nothing else caps folder creation. `prepareRootFolder`
+   * contributes exactly one more folder when it runs.
+   */
+  const materializedItems =
+    safeEntries.length +
+    impliedFolderPaths.size +
+    (safeEntries.length > 0 && prepareRootFolder ? 1 : 0)
+  if (materializedItems > maxMaterializedItems) {
+    throw new ArchiveError(
+      'too_many_entries',
+      `Archive would create ${materializedItems} files and folders; the maximum is ${maxMaterializedItems}.`
+    )
+  }
 
   // Cheap declared-size fast-reject for honestly-declared archives.
   let declaredTotal = 0
@@ -412,7 +426,10 @@ export async function decompressArchiveBufferToWorkspaceFiles(
     safeEntries.length > 0 && prepareRootFolder
       ? await prepareRootFolder(validateRootFolderSegments)
       : rootFolderSegments
-  validateRootFolderSegments(resolvedRootFolderSegments)
+  // Re-check what the callback actually returned; identical segments were proven above.
+  if (resolvedRootFolderSegments !== rootFolderSegments) {
+    validateRootFolderSegments(resolvedRootFolderSegments)
+  }
 
   // Pass 2 — extract: the archive is proven within caps; inflate again and upload.
   // Uploads themselves can still fail mid-loop (storage/DB errors, quota crossed

apps/sim/lib/uploads/contexts/workspace/workspace-file-folder-manager.ts

@@ -522,20 +522,20 @@ export async function createWorkspaceFileFolder(params: {
       }
     }
 
-    const name =
-      params.exactName === false
-        ? await deduplicateFolderName(
-            tx,
-            params.workspaceId,
-            parentId,
-            requestedName,
-            FILE_FOLDER_RESOURCE_TYPE
-          )
-        : requestedName
+    const deduplicate = params.exactName === false
+    const name = deduplicate
+      ? await deduplicateFolderName(
+          tx,
+          params.workspaceId,
+          parentId,
+          requestedName,
+          FILE_FOLDER_RESOURCE_TYPE
+        )
+      : requestedName
 
     params.validateResolvedName?.(name)
 
-    if (params.exactName !== false) {
+    if (!deduplicate) {
       const existingFolders = await tx
         .select({ id: folderTable.id })
         .from(folderTable)
@@ -1594,20 +1594,19 @@ export async function archiveWorkspaceFileFolderIfEmpty(params: {
   workspaceId: string
   folderId: string
 }): Promise<boolean> {
+  const isTargetFolder = and(
+    eq(folderTable.id, params.folderId),
+    eq(folderTable.workspaceId, params.workspaceId),
+    isFileFolder,
+    isNull(folderTable.deletedAt)
+  )
   return db.transaction(async (tx) => {
     await acquireWorkspaceFileFolderMutationLock(tx, params.workspaceId)
 
     const [folder] = await tx
       .select({ id: folderTable.id })
       .from(folderTable)
-      .where(
-        and(
-          eq(folderTable.id, params.folderId),
-          eq(folderTable.workspaceId, params.workspaceId),
-          isFileFolder,
-          isNull(folderTable.deletedAt)
-        )
-      )
+      .where(isTargetFolder)
       .limit(1)
     if (!folder) return false
 
@@ -1640,14 +1639,7 @@ export async function archiveWorkspaceFileFolderIfEmpty(params: {
     const [archived] = await tx
       .update(folderTable)
       .set({ deletedAt: new Date(), updatedAt: new Date() })
-      .where(
-        and(
-          eq(folderTable.id, params.folderId),
-          eq(folderTable.workspaceId, params.workspaceId),
-          isFileFolder,
-          isNull(folderTable.deletedAt)
-        )
-      )
+      .where(isTargetFolder)
       .returning({ id: folderTable.id })
     return Boolean(archived)
   })

apps/sim/lib/uploads/contexts/workspace/workspace-file-manager.ts

@@ -2073,6 +2073,17 @@ export async function purgeCreatedWorkspaceFile(params: {
     params.expectedFolderId === null
       ? isNull(workspaceFiles.folderId)
       : eq(workspaceFiles.folderId, params.expectedFolderId)
+  /** The full creation identity. Shared so the lock and the delete can never diverge. */
+  const matchesCreatedFile = and(
+    eq(workspaceFiles.id, params.fileId),
+    eq(workspaceFiles.workspaceId, params.workspaceId),
+    eq(workspaceFiles.key, params.key),
+    eq(workspaceFiles.originalName, params.expectedName),
+    expectedFolder,
+    eq(workspaceFiles.updatedAt, params.expectedUpdatedAt),
+    eq(workspaceFiles.context, 'workspace'),
+    isNull(workspaceFiles.deletedAt)
+  )
   const cleanupEventId = await db.transaction(async (tx) => {
     const [lockedFile] = await tx
       .select({
@@ -2082,36 +2093,14 @@ export async function purgeCreatedWorkspaceFile(params: {
         sizeBytes: workspaceFiles.sizeBytes,
       })
       .from(workspaceFiles)
-      .where(
-        and(
-          eq(workspaceFiles.id, params.fileId),
-          eq(workspaceFiles.workspaceId, params.workspaceId),
-          eq(workspaceFiles.key, params.key),
-          eq(workspaceFiles.originalName, params.expectedName),
-          expectedFolder,
-          eq(workspaceFiles.updatedAt, params.expectedUpdatedAt),
-          eq(workspaceFiles.context, 'workspace'),
-          isNull(workspaceFiles.deletedAt)
-        )
-      )
+      .where(matchesCreatedFile)
       .for('update')
       .limit(1)
     if (!lockedFile) return null
 
     const [deleted] = await tx
       .delete(workspaceFiles)
-      .where(
-        and(
-          eq(workspaceFiles.id, params.fileId),
-          eq(workspaceFiles.workspaceId, params.workspaceId),
-          eq(workspaceFiles.key, params.key),
-          eq(workspaceFiles.originalName, params.expectedName),
-          expectedFolder,
-          eq(workspaceFiles.updatedAt, params.expectedUpdatedAt),
-          eq(workspaceFiles.context, 'workspace'),
-          isNull(workspaceFiles.deletedAt)
-        )
-      )
+      .where(matchesCreatedFile)
       .returning({ id: workspaceFiles.id })
     if (!deleted) throw new Error('Locked archive-created file could not be deleted')