chore: import upstream snapshot with attribution

apps/sim/lib/uploads/contexts/workspace/fetch-external-url.test.ts

@@ -0,0 +1,237 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  inputValidationMock,
+  inputValidationMockFns,
+  permissionsMock,
+  permissionsMockFns,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockUploadWorkspaceFile } = vi.hoisted(() => ({
+  mockUploadWorkspaceFile: vi.fn(),
+}))
+
+vi.mock('@/lib/core/security/input-validation.server', () => inputValidationMock)
+vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
+vi.mock('@/lib/uploads/contexts/workspace/workspace-file-manager', () => ({
+  uploadWorkspaceFile: mockUploadWorkspaceFile,
+}))
+
+import {
+  ExternalUrlValidationError,
+  fetchExternalUrlToWorkspace,
+} from '@/lib/uploads/contexts/workspace/fetch-external-url'
+
+function makeResponse(body: string, contentType = 'application/octet-stream'): Response {
+  return new Response(body, { status: 200, headers: { 'content-type': contentType } })
+}
+
+describe('fetchExternalUrlToWorkspace', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    inputValidationMockFns.mockValidateUrlWithDNS.mockResolvedValue({
+      isValid: true,
+      resolvedIP: '203.0.113.10',
+    })
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('write')
+    mockUploadWorkspaceFile.mockImplementation(
+      async (workspaceId: string, _userId: string, _buffer: Buffer, fileName: string) => ({
+        id: `wf_${fileName}`,
+        name: fileName,
+        size: 0,
+        type: 'application/octet-stream',
+        url: `/api/files/serve/${workspaceId}/${fileName}`,
+        key: `${workspaceId}/${fileName}`,
+        context: 'workspace',
+      })
+    )
+  })
+
+  it('downloads each URL independently — never dedups by path filename', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP
+      .mockResolvedValueOnce(makeResponse('first bytes', 'image/png'))
+      .mockResolvedValueOnce(makeResponse('different second bytes', 'image/png'))
+
+    const first = await fetchExternalUrlToWorkspace({
+      url: 'https://files.slack.com/files-pri/T07-FAAA/download/image.png',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+    const second = await fetchExternalUrlToWorkspace({
+      url: 'https://files.slack.com/files-pri/T07-FBBB/download/image.png',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+
+    expect(first.filename).toBe('image.png')
+    expect(second.filename).toBe('image.png')
+    expect(first.buffer.toString()).toBe('first bytes')
+    expect(second.buffer.toString()).toBe('different second bytes')
+    expect(inputValidationMockFns.mockSecureFetchWithPinnedIP).toHaveBeenCalledTimes(2)
+    expect(mockUploadWorkspaceFile).toHaveBeenCalledTimes(2)
+  })
+
+  it('throws ExternalUrlValidationError when SSRF validation fails', async () => {
+    inputValidationMockFns.mockValidateUrlWithDNS.mockResolvedValue({
+      isValid: false,
+      error: 'Blocked private IP',
+    })
+
+    await expect(
+      fetchExternalUrlToWorkspace({
+        url: 'http://169.254.169.254/secret',
+        userId: 'user-1',
+      })
+    ).rejects.toBeInstanceOf(ExternalUrlValidationError)
+    expect(inputValidationMockFns.mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
+  })
+
+  it('throws on non-2xx fetch responses', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      new Response('not found', { status: 404, statusText: 'Not Found' })
+    )
+
+    await expect(
+      fetchExternalUrlToWorkspace({
+        url: 'https://example.com/missing.txt',
+        userId: 'user-1',
+      })
+    ).rejects.toThrow(/404/)
+  })
+
+  it('skips workspace save when saveToWorkspace is false', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/file.txt',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+      saveToWorkspace: false,
+    })
+
+    expect(result.savedWorkspaceFile).toBeUndefined()
+    expect(mockUploadWorkspaceFile).not.toHaveBeenCalled()
+    expect(permissionsMockFns.mockGetUserEntityPermissions).not.toHaveBeenCalled()
+  })
+
+  it('skips workspace save when no workspaceId is provided', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/file.txt',
+      userId: 'user-1',
+    })
+
+    expect(result.savedWorkspaceFile).toBeUndefined()
+    expect(mockUploadWorkspaceFile).not.toHaveBeenCalled()
+  })
+
+  it('skips workspace save when user lacks write permission', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue('read')
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/file.txt',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+
+    expect(result.savedWorkspaceFile).toBeUndefined()
+    expect(mockUploadWorkspaceFile).not.toHaveBeenCalled()
+  })
+
+  it('returns parsed bytes but skips save when user is not a workspace member', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+    permissionsMockFns.mockGetUserEntityPermissions.mockResolvedValue(null)
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/file.txt',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+
+    expect(result.buffer.toString()).toBe('bytes')
+    expect(result.savedWorkspaceFile).toBeUndefined()
+    expect(mockUploadWorkspaceFile).not.toHaveBeenCalled()
+  })
+
+  it('returns the saved workspace file when permission allows save', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/notes.txt',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+
+    expect(mockUploadWorkspaceFile).toHaveBeenCalledWith(
+      'workspace-1',
+      'user-1',
+      expect.any(Buffer),
+      'notes.txt',
+      'text/plain'
+    )
+    expect(result.savedWorkspaceFile?.key).toBe('workspace-1/notes.txt')
+  })
+
+  it('swallows workspace save errors so parsing can still proceed', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+    mockUploadWorkspaceFile.mockRejectedValueOnce(new Error('disk full'))
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/file.txt',
+      userId: 'user-1',
+      workspaceId: 'workspace-1',
+    })
+
+    expect(result.buffer.toString()).toBe('bytes')
+    expect(result.savedWorkspaceFile).toBeUndefined()
+  })
+
+  it('forwards custom headers to the fetch', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('bytes', 'text/plain')
+    )
+
+    await fetchExternalUrlToWorkspace({
+      url: 'https://files.slack.com/files-pri/T07/download/report.txt',
+      userId: 'user-1',
+      headers: { Authorization: 'Bearer xoxb-test-token' },
+    })
+
+    expect(inputValidationMockFns.mockSecureFetchWithPinnedIP).toHaveBeenCalledWith(
+      'https://files.slack.com/files-pri/T07/download/report.txt',
+      '203.0.113.10',
+      expect.objectContaining({
+        headers: { Authorization: 'Bearer xoxb-test-token' },
+      })
+    )
+  })
+
+  it('uses content-type from response headers', async () => {
+    inputValidationMockFns.mockSecureFetchWithPinnedIP.mockResolvedValue(
+      makeResponse('pdf bytes', 'application/pdf')
+    )
+
+    const result = await fetchExternalUrlToWorkspace({
+      url: 'https://example.com/report.pdf',
+      userId: 'user-1',
+    })
+
+    expect(result.mimeType).toBe('application/pdf')
+  })
+})

apps/sim/lib/uploads/contexts/workspace/fetch-external-url.ts

@@ -0,0 +1,155 @@
+import type { Buffer } from 'buffer'
+import path from 'path'
+import { createLogger } from '@sim/logger'
+import {
+  secureFetchWithPinnedIP,
+  validateUrlWithDNS,
+} from '@/lib/core/security/input-validation.server'
+import {
+  DEFAULT_MAX_ERROR_BODY_BYTES,
+  readResponseTextWithLimit,
+  readResponseToBufferWithLimit,
+} from '@/lib/core/utils/stream-limits'
+import { uploadWorkspaceFile } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
+import { getMimeTypeFromExtension } from '@/lib/uploads/utils/file-utils'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+import type { UserFile } from '@/executor/types'
+
+const logger = createLogger('FetchExternalUrl')
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024
+
+/**
+ * Thrown when the URL fails SSRF/DNS validation. Callers should map this to a
+ * user-facing 4xx-style response rather than a generic fetch failure.
+ */
+export class ExternalUrlValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ExternalUrlValidationError'
+  }
+}
+
+export interface FetchExternalUrlOptions {
+  url: string
+  userId: string
+  /** When provided alongside `saveToWorkspace: true`, the downloaded bytes are persisted as a workspace file. */
+  workspaceId?: string
+  /** Defaults to true when a `workspaceId` is provided. Set false when the URL already points at our own storage. */
+  saveToWorkspace?: boolean
+  headers?: Record<string, string>
+  signal?: AbortSignal
+  maxDownloadBytes?: number
+  timeoutMs?: number
+}
+
+export interface FetchExternalUrlResult {
+  /**
+   * Filename derived from the URL path. NOT a content identity — distinct URLs
+   * frequently share the same path tail (e.g. every Slack clipboard paste is
+   * `image.png`). Never use this as a cache key.
+   */
+  filename: string
+  buffer: Buffer
+  /** Content-Type from the response, or inferred from the filename extension. */
+  mimeType: string
+  /**
+   * Saved workspace file record. Undefined when the workspace save was skipped
+   * (no workspaceId, `saveToWorkspace: false`, missing write permission, or a
+   * save error — the last is logged, not thrown, so the parse path stays alive).
+   */
+  savedWorkspaceFile?: UserFile
+}
+
+/**
+ * Fetch an external URL into memory and (optionally) save it as a fresh workspace file.
+ *
+ * URL fetches are NEVER deduplicated by filename. Two URLs whose paths end in
+ * `image.png` are two different fetches that produce two different workspace
+ * files; `uploadWorkspaceFile` allocates a unique on-disk name (`image.png`,
+ * `image (1).png`, ...) on the save side. Keying a cache by path tail would
+ * silently return stale bytes — that was the original bug this helper exists
+ * to make unrepresentable.
+ */
+export async function fetchExternalUrlToWorkspace(
+  options: FetchExternalUrlOptions
+): Promise<FetchExternalUrlResult> {
+  const {
+    url,
+    userId,
+    workspaceId,
+    saveToWorkspace = Boolean(workspaceId),
+    headers,
+    signal,
+    maxDownloadBytes = DEFAULT_MAX_DOWNLOAD_BYTES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  } = options
+
+  const urlValidation = await validateUrlWithDNS(url, 'fileUrl')
+  if (!urlValidation.isValid || !urlValidation.resolvedIP) {
+    throw new ExternalUrlValidationError(urlValidation.error || 'Invalid external URL')
+  }
+
+  const filename = new URL(url).pathname.split('/').pop() || 'download'
+  const extension = path.extname(filename).toLowerCase().substring(1)
+
+  const response = await secureFetchWithPinnedIP(url, urlValidation.resolvedIP, {
+    timeout: timeoutMs,
+    maxResponseBytes: maxDownloadBytes,
+    signal,
+    ...(headers && Object.keys(headers).length > 0 && { headers }),
+  })
+
+  if (!response.ok) {
+    await readResponseTextWithLimit(response, {
+      maxBytes: DEFAULT_MAX_ERROR_BODY_BYTES,
+      label: 'external url error body',
+      signal,
+    }).catch(() => '')
+    throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`)
+  }
+
+  const buffer = await readResponseToBufferWithLimit(response, {
+    maxBytes: maxDownloadBytes,
+    label: 'external url download',
+    signal,
+  })
+
+  const mimeType = response.headers.get('content-type') || getMimeTypeFromExtension(extension)
+
+  let savedWorkspaceFile: UserFile | undefined
+  if (workspaceId && saveToWorkspace) {
+    const permission = await getUserEntityPermissions(userId, 'workspace', workspaceId)
+    if (permission === 'admin' || permission === 'write') {
+      try {
+        savedWorkspaceFile = await uploadWorkspaceFile(
+          workspaceId,
+          userId,
+          buffer,
+          filename,
+          mimeType
+        )
+      } catch (saveError) {
+        logger.warn('Failed to save fetched URL to workspace storage', {
+          workspaceId,
+          filename,
+          saveError,
+        })
+      }
+    } else if (permission === null) {
+      logger.warn('Skipping workspace save: user is not a workspace member', {
+        userId,
+        workspaceId,
+      })
+    } else {
+      logger.warn('Skipping workspace save: user lacks write permission', {
+        userId,
+        workspaceId,
+        permission,
+      })
+    }
+  }
+
+  return { filename, buffer, mimeType, savedWorkspaceFile }
+}

apps/sim/lib/uploads/contexts/workspace/index.ts

@@ -0,0 +1,3 @@
+export * from './fetch-external-url'
+export * from './workspace-file-folder-manager'
+export * from './workspace-file-manager'

apps/sim/lib/uploads/contexts/workspace/track-chat-upload.test.ts

@@ -0,0 +1,161 @@
+/**
+ * @vitest-environment node
+ */
+
+import { dbChainMock, dbChainMockFns, resetDbChainMock } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@sim/db', () => dbChainMock)
+
+import { CHAT_DISPLAY_NAME_INDEX, suffixedName, trackChatUpload } from './workspace-file-manager'
+
+const CHAT_ID = '11111111-1111-1111-1111-111111111111'
+const WORKSPACE_ID = 'ws_1'
+const USER_ID = 'user_1'
+const S3_KEY = 'mothership/abc/123-image.png'
+
+describe('suffixedName', () => {
+  it('returns the original name for n <= 1', () => {
+    expect(suffixedName('image.png', 1)).toBe('image.png')
+    expect(suffixedName('image.png', 0)).toBe('image.png')
+  })
+
+  it('inserts " (n)" before the extension', () => {
+    expect(suffixedName('image.png', 2)).toBe('image (2).png')
+    expect(suffixedName('image.png', 3)).toBe('image (3).png')
+    expect(suffixedName('My File.tar.gz', 2)).toBe('My File.tar (2).gz')
+  })
+
+  it('appends " (n)" for extensionless names', () => {
+    expect(suffixedName('README', 2)).toBe('README (2)')
+    expect(suffixedName('Makefile', 5)).toBe('Makefile (5)')
+  })
+
+  it('treats dotfiles as extensionless (leading dot only)', () => {
+    expect(suffixedName('.env', 2)).toBe('.env (2)')
+    expect(suffixedName('.gitignore', 3)).toBe('.gitignore (3)')
+  })
+
+  it('treats trailing-dot names as extensionless', () => {
+    expect(suffixedName('weird.', 2)).toBe('weird. (2)')
+  })
+})
+
+describe('trackChatUpload', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+  })
+
+  it('flips an existing workspace-scope row to mothership and returns the displayName', async () => {
+    dbChainMockFns.returning.mockResolvedValueOnce([{ id: 'wf_existing' }])
+
+    const result = await trackChatUpload(
+      WORKSPACE_ID,
+      USER_ID,
+      CHAT_ID,
+      S3_KEY,
+      'image.png',
+      'image/png',
+      1024
+    )
+
+    expect(result).toEqual({ displayName: 'image.png' })
+    expect(dbChainMockFns.set).toHaveBeenCalledWith(
+      expect.objectContaining({
+        chatId: CHAT_ID,
+        context: 'mothership',
+        displayName: 'image.png',
+      })
+    )
+  })
+
+  it('inserts a new row when no existing key matches', async () => {
+    // UPDATE returns no rows — falls through to INSERT.
+    dbChainMockFns.returning.mockResolvedValueOnce([])
+
+    const result = await trackChatUpload(
+      WORKSPACE_ID,
+      USER_ID,
+      CHAT_ID,
+      S3_KEY,
+      'image.png',
+      'image/png',
+      1024
+    )
+
+    expect(result).toEqual({ displayName: 'image.png' })
+    expect(dbChainMockFns.values).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: S3_KEY,
+        chatId: CHAT_ID,
+        context: 'mothership',
+        originalName: 'image.png',
+        displayName: 'image.png',
+      })
+    )
+  })
+
+  it('retries with a suffixed displayName on collision against the chat displayName index', async () => {
+    // 23505 from the partial unique index on (chat_id, display_name) — the case we retry.
+    const displayNameCollision = Object.assign(new Error('duplicate key'), {
+      code: '23505',
+      constraint_name: CHAT_DISPLAY_NAME_INDEX,
+    })
+
+    // Attempt 1: UPDATE finds no row (returning -> []), then INSERT throws displayName 23505.
+    dbChainMockFns.returning.mockResolvedValueOnce([])
+    dbChainMockFns.values.mockRejectedValueOnce(displayNameCollision)
+
+    // Attempt 2: UPDATE finds no row, INSERT succeeds.
+    dbChainMockFns.returning.mockResolvedValueOnce([])
+    dbChainMockFns.values.mockResolvedValueOnce(undefined)
+
+    const result = await trackChatUpload(
+      WORKSPACE_ID,
+      USER_ID,
+      CHAT_ID,
+      S3_KEY,
+      'image.png',
+      'image/png',
+      1024
+    )
+
+    expect(result).toEqual({ displayName: 'image (2).png' })
+
+    const lastValuesCall =
+      dbChainMockFns.values.mock.calls[dbChainMockFns.values.mock.calls.length - 1]
+    expect(lastValuesCall[0]).toMatchObject({
+      displayName: 'image (2).png',
+      originalName: 'image.png',
+    })
+  })
+
+  it('does NOT retry on a 23505 from the active-key index (concurrent same-s3Key insert)', async () => {
+    // A racing concurrent trackChatUpload for the same s3Key hit INSERT first. Our INSERT
+    // 23505s on workspace_files_key_active_unique. Retrying with a suffixed displayName
+    // would let the next iteration UPDATE the racer's row and silently rename the path
+    // it already returned to its caller — so we throw instead.
+    const keyCollision = Object.assign(new Error('duplicate key'), {
+      code: '23505',
+      constraint_name: 'workspace_files_key_active_unique',
+    })
+
+    dbChainMockFns.returning.mockResolvedValueOnce([])
+    dbChainMockFns.values.mockRejectedValueOnce(keyCollision)
+
+    await expect(
+      trackChatUpload(WORKSPACE_ID, USER_ID, CHAT_ID, S3_KEY, 'image.png', 'image/png', 1024)
+    ).rejects.toThrow('duplicate key')
+
+    expect(dbChainMockFns.values).toHaveBeenCalledTimes(1)
+  })
+
+  it('rethrows non-unique-violation errors immediately', async () => {
+    dbChainMockFns.returning.mockRejectedValueOnce(new Error('connection lost'))
+
+    await expect(
+      trackChatUpload(WORKSPACE_ID, USER_ID, CHAT_ID, S3_KEY, 'image.png', 'image/png', 1024)
+    ).rejects.toThrow('connection lost')
+  })
+})

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

@@ -0,0 +1,33 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  buildWorkspaceFileFolderPathMap,
+  normalizeWorkspaceFileItemName,
+} from './workspace-file-folder-manager'
+
+describe('workspace file folder paths', () => {
+  it('builds nested paths from parent relationships', () => {
+    const paths = buildWorkspaceFileFolderPathMap([
+      { id: 'reports', name: 'Reports', parentId: null },
+      { id: 'quarterly', name: 'Quarterly', parentId: 'reports' },
+      { id: 'archive', name: 'Archive', parentId: null },
+    ])
+
+    expect(paths.get('reports')).toBe('Reports')
+    expect(paths.get('quarterly')).toBe('Reports/Quarterly')
+    expect(paths.get('archive')).toBe('Archive')
+  })
+
+  it('rejects names that would create ambiguous paths', () => {
+    expect(normalizeWorkspaceFileItemName('Reports', 'Folder')).toBe('Reports')
+    expect(() => normalizeWorkspaceFileItemName('A/B', 'Folder')).toThrow(
+      'Folder name cannot contain path separators or dot segments'
+    )
+    expect(() => normalizeWorkspaceFileItemName('..', 'File')).toThrow(
+      'File name cannot contain path separators or dot segments'
+    )
+  })
+})

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

@@ -0,0 +1,78 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  findWorkspaceFileRecord,
+  normalizeWorkspaceFileReference,
+  type WorkspaceFileRecord,
+} from './workspace-file-manager'
+
+const FILE_ID = 'ec28e5d5-898a-48f0-aa6f-2fd7427c9563'
+
+function makeFileRecord(): WorkspaceFileRecord {
+  return {
+    id: FILE_ID,
+    workspaceId: 'ws_123',
+    name: 'the_last_cartographer_of_vael.md',
+    key: 'workspace/ws_123/mock-key',
+    path: '/api/files/serve/mock-key?context=workspace',
+    size: 128,
+    type: 'text/markdown',
+    uploadedBy: 'user_123',
+    folderId: null,
+    folderPath: null,
+    uploadedAt: new Date('2026-04-13T00:00:00.000Z'),
+    updatedAt: new Date('2026-04-13T00:00:00.000Z'),
+  }
+}
+
+describe('workspace file reference normalization', () => {
+  it('normalizes canonical VFS paths to their sanitized display path', () => {
+    expect(normalizeWorkspaceFileReference('files/Reports/q1.csv/content')).toBe('Reports/q1.csv')
+    expect(normalizeWorkspaceFileReference('files/Reports/q1.csv/meta.json')).toBe('Reports/q1.csv')
+    expect(normalizeWorkspaceFileReference('recently-deleted/files/data.csv/content')).toBe(
+      'data.csv'
+    )
+  })
+
+  it('still resolves a raw file id passed directly', () => {
+    const files = [makeFileRecord()]
+
+    expect(findWorkspaceFileRecord(files, FILE_ID)).toMatchObject({
+      id: FILE_ID,
+      name: 'the_last_cartographer_of_vael.md',
+    })
+  })
+
+  it('does not resolve id-based VFS paths', () => {
+    const files = [makeFileRecord()]
+
+    expect(findWorkspaceFileRecord(files, `files/by-id/${FILE_ID}/content`)).toBeNull()
+  })
+
+  it('resolves duplicate names by folder-aware VFS path', () => {
+    const reportsFile: WorkspaceFileRecord = {
+      ...makeFileRecord(),
+      id: 'file-reports',
+      name: 'q1.csv',
+      folderId: 'folder-reports',
+      folderPath: 'Reports',
+    }
+    const archiveFile: WorkspaceFileRecord = {
+      ...makeFileRecord(),
+      id: 'file-archive',
+      name: 'q1.csv',
+      folderId: 'folder-archive',
+      folderPath: 'Archive',
+    }
+
+    expect(
+      findWorkspaceFileRecord([reportsFile, archiveFile], 'files/Reports/q1.csv/content')
+    ).toBe(reportsFile)
+    expect(findWorkspaceFileRecord([reportsFile, archiveFile], 'files/Archive/q1.csv')).toBe(
+      archiveFile
+    )
+  })
+})