fix(microsoft-word): guard document edits against concurrent overwrites

Author: waleedlatif1

apps/docs/content/docs/en/integrations/microsoft_word.mdx

@@ -79,7 +79,7 @@ Integrate Microsoft Word into the workflow. Create .docx documents from text, fi
 
 ### Create Microsoft Word Document
 
-Create a new Microsoft Word (.docx) document in OneDrive or SharePoint from text content. Supports Markdown headings (# ## ###), bullets (-), and inline **bold** / *italic*.
+Create a new Microsoft Word (.docx) document in OneDrive or SharePoint from text content. Supports Markdown headings (# ## ###), bullets (-), and inline **bold** / *italic*. An existing document with the same name is never overwritten — the new one is given a unique name instead.
 
 #### Input
 
@@ -105,7 +105,7 @@ Create a new Microsoft Word (.docx) document in OneDrive or SharePoint from text
 
 ### Create Microsoft Word Document from Template
 
-Copy an existing Microsoft Word (.docx) template to a new document and fill its placeholders. The template keeps all of its formatting, styles, headers, and footers, and is never modified.
+Copy an existing Microsoft Word (.docx) template to a new document and fill its placeholders. The template keeps all of its formatting, styles, headers, and footers, and is never modified. An existing document with the same name is never overwritten — the new one is given a unique name instead.
 
 #### Input
 
@@ -185,7 +185,7 @@ Replace the entire contents of an existing Microsoft Word (.docx) document with
 
 ### Append to Microsoft Word Document
 
-Append plain-text paragraphs to the end of an existing Microsoft Word (.docx) document, leaving the existing content and formatting intact.
+Append plain-text paragraphs to the end of an existing Microsoft Word (.docx) document, leaving the existing content and formatting intact. Fails rather than overwriting if someone else changed the document while the edit was in flight.
 
 #### Input
 
@@ -211,7 +211,7 @@ Append plain-text paragraphs to the end of an existing Microsoft Word (.docx) do
 
 ### Replace Text in Microsoft Word Document
 
-Find and replace text throughout a Microsoft Word (.docx) document, including its headers and footers. Use this to fill placeholders in a template document.
+Find and replace text throughout a Microsoft Word (.docx) document, including its headers and footers. Use this to fill placeholders in a template document. Fails rather than overwriting if someone else changed the document while the edit was in flight.
 
 #### Input
 

apps/sim/app/api/tools/microsoft_word/append/route.test.ts

@@ -0,0 +1,145 @@
+/**
+ * @vitest-environment node
+ */
+import {
+  createMockRequest,
+  hybridAuthMockFns,
+  inputValidationMock,
+  inputValidationMockFns,
+} from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/lib/core/security/input-validation.server', () => inputValidationMock)
+
+import { buildDocxFromContent } from '@/lib/microsoft-word/document.server'
+import { POST } from '@/app/api/tools/microsoft_word/append/route'
+
+const { mockValidateUrlWithDNS, mockSecureFetchWithPinnedIP } = inputValidationMockFns
+
+const PINNED_IP = '93.184.216.34'
+
+const baseBody = {
+  accessToken: 'token-123',
+  documentId: 'doc-abc',
+  content: 'Appended paragraph',
+}
+
+/** A Graph `driveItem` metadata response carrying a content tag. */
+function itemResponse(cTag: string) {
+  const body = {
+    id: 'doc-abc',
+    name: 'notes.docx',
+    cTag,
+    file: { mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' },
+  }
+  return {
+    ok: true,
+    status: 200,
+    statusText: '',
+    headers: new Headers(),
+    body: null,
+    text: async () => JSON.stringify(body),
+    json: async () => body,
+    arrayBuffer: async () => new ArrayBuffer(0),
+  }
+}
+
+/** A Graph content response carrying a real `.docx` package. */
+async function docxResponse() {
+  const buffer = await buildDocxFromContent('Existing paragraph')
+  return {
+    ok: true,
+    status: 200,
+    statusText: '',
+    headers: new Headers(),
+    body: null,
+    text: async () => '',
+    json: async () => ({}),
+    arrayBuffer: async () =>
+      buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+  }
+}
+
+function preconditionFailedResponse() {
+  return {
+    ok: false,
+    status: 412,
+    statusText: 'Precondition Failed',
+    headers: new Headers(),
+    body: null,
+    text: async () => '',
+    json: async () => ({}),
+    arrayBuffer: async () => new ArrayBuffer(0),
+  }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  hybridAuthMockFns.mockCheckInternalAuth.mockResolvedValue({
+    success: true,
+    userId: 'user-1',
+    authType: 'internal_jwt',
+  })
+  mockValidateUrlWithDNS.mockResolvedValue({
+    isValid: true,
+    resolvedIP: PINNED_IP,
+    originalHostname: 'graph.microsoft.com',
+  })
+})
+
+describe('POST /api/tools/microsoft_word/append', () => {
+  it('uploads the edit when the document has not changed, guarded by its content tag', async () => {
+    mockSecureFetchWithPinnedIP
+      .mockResolvedValueOnce(itemResponse('tag-1'))
+      .mockResolvedValueOnce(await docxResponse())
+      .mockResolvedValueOnce(itemResponse('tag-1'))
+      .mockResolvedValueOnce(itemResponse('tag-2'))
+
+    const response = await POST(createMockRequest('POST', baseBody))
+
+    expect(response.status).toBe(200)
+    const data = (await response.json()) as {
+      success: boolean
+      output: { updatedContent: boolean }
+    }
+    expect(data.success).toBe(true)
+    expect(data.output.updatedContent).toBe(true)
+
+    const uploadCall = mockSecureFetchWithPinnedIP.mock.calls.at(-1)
+    expect(uploadCall?.[2]).toMatchObject({ method: 'PUT' })
+    expect(uploadCall?.[2].headers).toMatchObject({ 'if-match': 'tag-1' })
+  })
+
+  it('refuses to overwrite a document that changed while the edit was in flight', async () => {
+    mockSecureFetchWithPinnedIP
+      .mockResolvedValueOnce(itemResponse('tag-1'))
+      .mockResolvedValueOnce(await docxResponse())
+      .mockResolvedValueOnce(itemResponse('tag-2'))
+
+    const response = await POST(createMockRequest('POST', baseBody))
+
+    expect(response.status).toBe(409)
+    const data = (await response.json()) as { success: boolean; error: string }
+    expect(data.success).toBe(false)
+    expect(data.error).toMatch(/no other change was overwritten/)
+
+    // The conflict is detected before the PUT, so nothing was written.
+    expect(mockSecureFetchWithPinnedIP.mock.calls.some((call) => call[2]?.method === 'PUT')).toBe(
+      false
+    )
+  })
+
+  it('surfaces a 412 from the upload precondition as the same conflict', async () => {
+    mockSecureFetchWithPinnedIP
+      .mockResolvedValueOnce(itemResponse('tag-1'))
+      .mockResolvedValueOnce(await docxResponse())
+      .mockResolvedValueOnce(itemResponse('tag-1'))
+      .mockResolvedValueOnce(preconditionFailedResponse())
+
+    const response = await POST(createMockRequest('POST', baseBody))
+
+    expect(response.status).toBe(409)
+    const data = (await response.json()) as { error: string }
+    expect(data.error).toMatch(/no other change was overwritten/)
+  })
+})

apps/sim/app/api/tools/microsoft_word/append/route.ts

@@ -7,8 +7,10 @@ import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { appendParagraphsToDocx, DOCX_MIME_TYPE } from '@/lib/microsoft-word/document.server'
 import {
+  assertContentUnchanged,
   downloadDocumentContent,
   fetchDocumentItem,
+  getContentTag,
   toDocumentMetadata,
   uploadDocumentContent,
 } from '@/lib/microsoft-word/graph.server'
@@ -42,16 +44,19 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
   try {
     const basePath = getDocumentBasePath(documentId, driveId ?? undefined)
-    await fetchDocumentItem(basePath, accessToken)
+    const contentTag = getContentTag(await fetchDocumentItem(basePath, accessToken))
 
     const existingBuffer = await downloadDocumentContent(basePath, accessToken)
     const updatedBuffer = await appendParagraphsToDocx(existingBuffer, content)
 
+    await assertContentUnchanged(basePath, accessToken, contentTag)
+
     const item = await uploadDocumentContent(
       `${basePath}/content`,
       accessToken,
       updatedBuffer,
-      DOCX_MIME_TYPE
+      DOCX_MIME_TYPE,
+      contentTag
     )
 
     logger.info(`[${requestId}] Appended to Word document`, { documentId, size: item.size })

apps/sim/app/api/tools/microsoft_word/create-from-template/route.ts

@@ -18,6 +18,7 @@ import {
 } from '@/lib/microsoft-word/graph.server'
 import { microsoftWordErrorResponse } from '@/app/api/tools/microsoft_word/utils'
 import {
+  buildCreateUploadUrl,
   ensureDocxExtension,
   getDocumentBasePath,
   getDriveBasePath,
@@ -71,7 +72,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     const parentPath = folderId?.trim()
       ? getFolderBasePath(folderId, driveId ?? undefined)
       : `${getDriveBasePath(driveId ?? undefined)}/root`
-    const uploadUrl = `${parentPath}:/${encodeURIComponent(fileName)}:/content`
+    const uploadUrl = buildCreateUploadUrl(parentPath, fileName)
 
     const item = await uploadDocumentContent(uploadUrl, accessToken, filled.buffer, DOCX_MIME_TYPE)
 

apps/sim/app/api/tools/microsoft_word/create/route.ts

@@ -9,6 +9,7 @@ import { buildDocxFromContent, DOCX_MIME_TYPE } from '@/lib/microsoft-word/docum
 import { toDocumentMetadata, uploadDocumentContent } from '@/lib/microsoft-word/graph.server'
 import { microsoftWordErrorResponse } from '@/app/api/tools/microsoft_word/utils'
 import {
+  buildCreateUploadUrl,
   ensureDocxExtension,
   getDriveBasePath,
   getFolderBasePath,
@@ -46,7 +47,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     const parentPath = folderId?.trim()
       ? getFolderBasePath(folderId, driveId ?? undefined)
       : `${getDriveBasePath(driveId ?? undefined)}/root`
-    const uploadUrl = `${parentPath}:/${encodeURIComponent(fileName)}:/content`
+    const uploadUrl = buildCreateUploadUrl(parentPath, fileName)
 
     const documentBuffer = await buildDocxFromContent(content ?? '', name)
     const item = await uploadDocumentContent(uploadUrl, accessToken, documentBuffer, DOCX_MIME_TYPE)

apps/sim/app/api/tools/microsoft_word/replace-text/route.ts

@@ -7,8 +7,10 @@ import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { DOCX_MIME_TYPE, replaceTextInDocx } from '@/lib/microsoft-word/document.server'
 import {
+  assertContentUnchanged,
   downloadDocumentContent,
   fetchDocumentItem,
+  getContentTag,
   toDocumentMetadata,
   uploadDocumentContent,
 } from '@/lib/microsoft-word/graph.server'
@@ -44,6 +46,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   try {
     const basePath = getDocumentBasePath(documentId, driveId ?? undefined)
     const existingItem = await fetchDocumentItem(basePath, accessToken)
+    const contentTag = getContentTag(existingItem)
 
     const existingBuffer = await downloadDocumentContent(basePath, accessToken)
     const { buffer, occurrencesChanged } = await replaceTextInDocx(
@@ -63,11 +66,14 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       })
     }
 
+    await assertContentUnchanged(basePath, accessToken, contentTag)
+
     const item = await uploadDocumentContent(
       `${basePath}/content`,
       accessToken,
       buffer,
-      DOCX_MIME_TYPE
+      DOCX_MIME_TYPE,
+      contentTag
     )
 
     logger.info(`[${requestId}] Replaced text in Word document`, {

apps/sim/lib/microsoft-word/graph.server.ts

@@ -14,10 +14,28 @@ interface GraphDriveItem {
   webUrl?: string
   createdDateTime?: string
   lastModifiedDateTime?: string
+  /** An eTag for the item's content, unchanged when only metadata changes. */
+  cTag?: string
+  /** An eTag for the whole item, metadata included. */
+  eTag?: string
   file?: { mimeType?: string }
   folder?: Record<string, unknown>
 }
 
+/**
+ * The token that identifies the exact content an edit was based on.
+ *
+ * `cTag` is the right one: Graph documents it as "an eTag for the content of the
+ * item" that does not move when only metadata changes, so a rename will not
+ * spuriously abort an edit. `eTag` is the fallback for the shapes where Graph
+ * omits `cTag`.
+ *
+ * @see https://learn.microsoft.com/en-us/graph/api/resources/driveitem
+ */
+export function getContentTag(item: GraphDriveItem): string | undefined {
+  return item.cTag ?? item.eTag
+}
+
 /** Thrown when Microsoft Graph rejects a request, carrying its HTTP status. */
 export class GraphRequestError extends Error {
   constructor(
@@ -143,27 +161,72 @@ export async function downloadConvertedContent(
   return Buffer.from(await response.arrayBuffer())
 }
 
+/** Message shown when someone else changed the document mid-edit. */
+const CONFLICT_MESSAGE =
+  'The document changed in OneDrive or SharePoint after Sim read it, so the edit was not applied and no other change was overwritten. Run the operation again to edit the current version.'
+
+/** Raised instead of overwriting a document that changed since it was read. */
+export function documentChangedError(): GraphRequestError {
+  return new GraphRequestError(CONFLICT_MESSAGE, 409)
+}
+
+/**
+ * Aborts a read-modify-write when the document's content changed since it was
+ * read. Without this, two overlapping edits both succeed and the later upload
+ * silently discards the earlier one.
+ *
+ * `expected` being undefined means Graph returned neither tag for this item, so
+ * there is nothing to compare and the caller proceeds unguarded — the
+ * `if-match` header on the upload is the remaining line of defense.
+ */
+export async function assertContentUnchanged(
+  basePath: string,
+  accessToken: string,
+  expected: string | undefined
+): Promise<void> {
+  if (!expected) return
+
+  const current = getContentTag(await fetchDocumentItem(basePath, accessToken))
+  if (current && current !== expected) {
+    throw documentChangedError()
+  }
+}
+
 /**
  * Uploads bytes as a drive item's content and returns the resulting item.
  *
+ * `ifMatch` carries the content tag the upload is based on. Graph documents
+ * `if-match` (and its `412 Precondition Failed` response) on the metadata
+ * update, not on this content endpoint, so it is sent as a second line of
+ * defense rather than the guarantee: an `If-Match` a server does not implement
+ * is ignored, and the caller's {@link assertContentUnchanged} check is what
+ * actually decides whether the write is safe. A `412` is surfaced as the same
+ * conflict either way.
+ *
  * @see https://learn.microsoft.com/en-us/graph/api/driveitem-put-content
+ * @see https://learn.microsoft.com/en-us/graph/api/driveitem-update
  */
 export async function uploadDocumentContent(
   url: string,
   accessToken: string,
   content: Buffer,
-  mimeType: string
+  mimeType: string,
+  ifMatch?: string
 ): Promise<GraphDriveItem> {
   const response = await graphFetch(url, 'documentUploadUrl', {
     method: 'PUT',
     headers: {
       Authorization: `Bearer ${accessToken}`,
       'Content-Type': mimeType,
       'Content-Length': String(content.length),
+      ...(ifMatch ? { 'if-match': ifMatch } : {}),
     },
     body: content,
   })
 
+  if (response.status === 412) {
+    throw documentChangedError()
+  }
   if (!response.ok) await raiseGraphError(response)
 
   return (await response.json()) as GraphDriveItem

apps/sim/tools/generated/tool-metadata.ts

@@ -9,7 +9,7 @@ export const appendTool: ToolConfig<MicrosoftWordToolParams, MicrosoftWordUpdate
   id: 'microsoft_word_append',
   name: 'Append to Microsoft Word Document',
   description:
-    'Append plain-text paragraphs to the end of an existing Microsoft Word (.docx) document, leaving the existing content and formatting intact.',
+    'Append plain-text paragraphs to the end of an existing Microsoft Word (.docx) document, leaving the existing content and formatting intact. Fails rather than overwriting if someone else changed the document while the edit was in flight.',
   version: '1.0',
   errorExtractor: ErrorExtractorId.MICROSOFT_GRAPH_ERRORS,