security: restrict upload_attachment file access to upload root

packages/core/src/bookstack-client.ts

@@ -24,6 +24,7 @@ export class BookStackClient {
   private readonly tokenId: string;
   private readonly tokenSecret: string;
   private readonly enableWrite: boolean;
+  private readonly uploadRoot: string | undefined;
   private bookSlugCache: Map<number, string> = new Map();
   private pageInfoCache: Map<number, { slug: string; bookId: number }> = new Map();
 
@@ -32,6 +33,7 @@ export class BookStackClient {
     this.tokenId = config.tokenId;
     this.tokenSecret = config.tokenSecret;
     this.enableWrite = config.enableWrite ?? false;
+    this.uploadRoot = config.uploadRoot;
   }
 
   private async request<T>(
@@ -947,9 +949,14 @@ export class BookStackClient {
     if (!this.enableWrite) {
       throw new Error('Write operations are disabled. Set BOOKSTACK_ENABLE_WRITE=true to enable.');
     }
-    const absolutePath = data.file_path.startsWith('~')
+    const expandedPath = data.file_path.startsWith('~')
       ? data.file_path.replace('~', process.env.HOME ?? '')
       : data.file_path;
+    const absolutePath = path.resolve(expandedPath);
+    const uploadRoot = this.uploadRoot ? path.resolve(this.uploadRoot) : path.resolve('.');
+    if (!absolutePath.startsWith(uploadRoot + path.sep) && absolutePath !== uploadRoot) {
+      throw new Error(`File path must be within the upload root directory: ${uploadRoot}`);
+    }
     if (!fs.existsSync(absolutePath)) {
       throw new Error(`File not found: ${absolutePath}`);
     }

packages/core/src/types.ts

@@ -3,6 +3,7 @@ export interface BookStackConfig {
   tokenId: string;
   tokenSecret: string;
   enableWrite?: boolean;
+  uploadRoot?: string;
 }
 
 export interface Book {

packages/core/tests/api-methods.test.ts

@@ -74,7 +74,7 @@ beforeEach(() => {
   vi.useFakeTimers();
   vi.setSystemTime(NOW);
   rc = new BookStackClient({ baseUrl: BASE, tokenId: 'id', tokenSecret: 'sec' });
-  wc = new BookStackClient({ baseUrl: BASE, tokenId: 'id', tokenSecret: 'sec', enableWrite: true });
+  wc = new BookStackClient({ baseUrl: BASE, tokenId: 'id', tokenSecret: 'sec', enableWrite: true, uploadRoot: '/tmp' });
 });
 
 afterEach(() => {
@@ -755,6 +755,18 @@ describe('uploadAttachment', () => {
     ).rejects.toThrow('File not found');
   });
 
+  it('throws when file path is outside upload root', async () => {
+    await expect(
+      wc.uploadAttachment({ file_path: '/etc/passwd', uploaded_to: 10 })
+    ).rejects.toThrow('File path must be within the upload root directory');
+  });
+
+  it('throws when file path uses traversal to escape upload root', async () => {
+    await expect(
+      wc.uploadAttachment({ file_path: '/tmp/../etc/passwd', uploaded_to: 10 })
+    ).rejects.toThrow('File path must be within the upload root directory');
+  });
+
   it('throws when write is disabled', async () => {
     await expect(
       rc.uploadAttachment({ file_path: '/tmp/file.txt', uploaded_to: 10 })

packages/core/tests/helpers.ts

@@ -1,5 +1,6 @@
 import { BookStackClient, BookStackConfig } from '@bookstack-mcp/core';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -22,6 +23,7 @@ export function getTestConfig(enableWrite = true): BookStackConfig {
     tokenId: process.env.TEST_BOOKSTACK_TOKEN_ID || '',
     tokenSecret: process.env.TEST_BOOKSTACK_TOKEN_SECRET || '',
     enableWrite,
+    uploadRoot: os.tmpdir(),
   };
 }
 

packages/stdio/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bookstack-mcp-stdio",
-  "version": "2.6.1",
+  "version": "2.6.2",
   "description": "BookStack MCP server (stdio transport)",
   "type": "module",
   "main": "dist/index.js",

packages/stdio/src/index.ts

@@ -88,12 +88,16 @@ async function main() {
     baseUrl: validateBaseUrl(getRequiredEnvVar('BOOKSTACK_BASE_URL')),
     tokenId: getRequiredEnvVar('BOOKSTACK_TOKEN_ID'),
     tokenSecret: getRequiredEnvVar('BOOKSTACK_TOKEN_SECRET'),
-    enableWrite: process.env.BOOKSTACK_ENABLE_WRITE?.toLowerCase() === 'true'
+    enableWrite: process.env.BOOKSTACK_ENABLE_WRITE?.toLowerCase() === 'true',
+    uploadRoot: process.env.BOOKSTACK_UPLOAD_ROOT || undefined
   };
 
   console.error('Initializing BookStack MCP Server...');
   console.error(`BookStack URL: ${config.baseUrl}`);
   console.error(`Write operations: ${config.enableWrite ? 'ENABLED' : 'DISABLED'}`);
+  if (config.enableWrite) {
+    console.error(`Upload root: ${config.uploadRoot ?? process.cwd() + ' (default: cwd)'}`);
+  }
 
   const client = new BookStackClient(config);
   const server = new McpServer({