fix: prevent path traversal in style and tileset tool URL construction (#103)

* fix: prevent path traversal in style and tileset tool URL construction

Five tools (RetrieveStyle, DeleteStyle, UpdateStyle, PreviewStyle,
TilequeryTool) concatenated user-supplied path parameters directly
into Mapbox API URLs without validation or encoding. Because Node.js
fetch uses the WHATWG URL parser, `../` sequences were normalized
before sending, allowing requests to reach unintended API endpoints.

Changes:
- Add shared `styleIdSchema` with allowlist regex that rejects path
  separators, dots, percent-encoded sequences, and null bytes
- Apply `styleIdSchema` to all four style tools via a shared module
  (src/tools/shared/styleId.schema.ts)
- Add format validation to TilequeryTool tilesetId (owner.name format)
- Wrap both username and styleId/tilesetId in `encodeURIComponent`
  at every URL construction site (defense-in-depth)
- Replace silent fallback in output schema validation with explicit
  `isError: true` responses across all API tools, preventing
  unintended API responses from being forwarded to callers
- Remove now-unused BaseTool.validateOutput() method
- Add test/security/path-traversal.test.ts with 52 tests covering
  schema rejection, valid ID acceptance, URL encoding, and response
  schema mismatch behavior

* fix: update tests for Prettier, Zod v4, and @mcp-ui/server v6.1.0 upgrades

- Reformat dynamic imports to match Prettier 3.8.x style
- Update Zod v4 error code assertions (invalid_value, too_big)
- Update mimeType assertions for @mcp-ui/server v6.1.0 (text/html;profile=mcp-app)
- Fix PreviewStyleTool test mimeType expectation

* fix: reject cross-origin Link headers and redact tokens from logs

- Validate that pagination next-page URLs from Link response headers
  share the same origin as the configured API endpoint; cross-origin
  URLs are rejected to prevent access token exfiltration
- Add redactToken() utility that strips access_token query parameter
  values from strings before they reach log output or MCP client error
  responses (network errors include the full request URL in their
  message which would otherwise expose the token)
- Remove full URL from info/debug level pagination log messages

* refactor: extract handleValidationError helper and include error details in validation failures

* test: assert validation error details are included in error response

* test: add validation error response tests for TilequeryTool and RetrieveStyleTool

Author: zmofei

src/tools/BaseTool.ts

@@ -135,26 +135,4 @@ export abstract class BaseTool<
       this.server.server.sendLoggingMessage({ level, data });
     }
   }
-
-  /**
-   * Validates output data against the output schema.
-   * If validation fails, logs a warning and returns the raw data instead of throwing an error.
-   * This allows tools to continue functioning when API responses deviate from expected schemas.
-   */
-  protected validateOutput<T>(
-    schema: ZodTypeAny,
-    rawData: unknown,
-    toolName: string
-  ): T {
-    try {
-      return schema.parse(rawData) as T;
-    } catch (validationError) {
-      this.log(
-        'warning',
-        `${toolName}: Output schema validation failed - ${validationError instanceof Error ? validationError.message : 'Unknown validation error'}`
-      );
-      // Graceful fallback to raw data
-      return rawData as T;
-    }
-  }
 }

src/tools/MapboxApiBasedTool.ts

@@ -13,6 +13,11 @@ import { context, trace, SpanStatusCode } from '@opentelemetry/api';
 import type { ToolExecutionContext } from '../utils/tracing.js';
 import { createToolExecutionContext } from '../utils/tracing.js';
 
+/** Remove access_token query parameter values from strings before logging or returning to callers. */
+export function redactToken(s: string): string {
+  return s.replace(/access_token=[^&\s#"']+/g, 'access_token=***');
+}
+
 /**
  * Standard error response format from Mapbox API
  */
@@ -126,8 +131,8 @@ export abstract class MapboxApiBasedTool<
       toolContext.span.end();
       return result;
     } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage = redactToken(rawMessage);
       this.log(
         'error',
         `${this.name}: Error during execution: ${errorMessage}`
@@ -212,6 +217,18 @@ export abstract class MapboxApiBasedTool<
     };
   }
 
+  protected handleValidationError(error: unknown): CallToolResult {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Unexpected API response format from Mapbox API: ${error instanceof Error ? error.message : 'Unknown validation error'}`
+        }
+      ]
+    };
+  }
+
   /**
    * Tool logic to be implemented by subclasses.
    * Must return a complete OutputSchema with content and optional structured content.

src/tools/create-token-tool/CreateTokenTool.ts

@@ -92,12 +92,12 @@ export class CreateTokenTool extends MapboxApiBasedTool<
 
     const rawData = await response.json();
 
-    // Validate response against schema with graceful fallback
-    const data = this.validateOutput<Record<string, unknown>>(
-      CreateTokenOutputSchema,
-      rawData,
-      'CreateTokenTool'
-    );
+    let data;
+    try {
+      data = CreateTokenOutputSchema.parse(rawData);
+    } catch (validationError) {
+      return this.handleValidationError(validationError);
+    }
 
     this.log('info', `CreateTokenTool: Successfully created token`);
 

src/tools/delete-style-tool/DeleteStyleTool.input.schema.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { styleIdSchema } from '../shared/styleId.schema.js';
 
 export const DeleteStyleSchema = z.object({
-  styleId: z.string().describe('Style ID to delete')
+  styleId: styleIdSchema.describe('Style ID to delete')
 });
 
 export type DeleteStyleInput = z.infer<typeof DeleteStyleSchema>;

src/tools/delete-style-tool/DeleteStyleTool.ts

@@ -34,7 +34,7 @@ export class DeleteStyleTool extends MapboxApiBasedTool<
     _context: ToolExecutionContext
   ): Promise<CallToolResult> {
     const username = getUserNameFromToken(accessToken);
-    const url = `${MapboxApiBasedTool.mapboxApiEndpoint}styles/v1/${username}/${input.styleId}?access_token=${accessToken}`;
+    const url = `${MapboxApiBasedTool.mapboxApiEndpoint}styles/v1/${encodeURIComponent(username)}/${encodeURIComponent(input.styleId)}?access_token=${accessToken}`;
 
     const response = await this.httpRequest(url, {
       method: 'DELETE'

src/tools/list-styles-tool/ListStylesTool.ts

@@ -70,12 +70,12 @@ export class ListStylesTool extends MapboxApiBasedTool<
 
     const rawData = await response.json();
 
-    // Validate the API response (which is an array) with graceful fallback
-    const validatedData = this.validateOutput(
-      StylesArraySchema,
-      rawData,
-      'ListStylesTool'
-    );
+    let validatedData;
+    try {
+      validatedData = StylesArraySchema.parse(rawData);
+    } catch (validationError) {
+      return this.handleValidationError(validationError);
+    }
 
     this.log('info', `ListStylesTool: Successfully listed styles`);
 

src/tools/list-tokens-tool/ListTokensTool.ts

@@ -4,7 +4,7 @@
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { HttpRequest } from '../../utils/types.js';
 import type { ToolExecutionContext } from '../../utils/tracing.js';
-import { MapboxApiBasedTool } from '../MapboxApiBasedTool.js';
+import { MapboxApiBasedTool, redactToken } from '../MapboxApiBasedTool.js';
 import {
   ListTokensSchema,
   ListTokensInput
@@ -110,7 +110,7 @@ export class ListTokensTool extends MapboxApiBasedTool<
       while (url) {
         pageCount++;
         this.log('info', `ListTokensTool: Fetching page ${pageCount}`);
-        this.log('debug', `ListTokensTool: Fetching URL: ${url}`);
+        this.log('debug', `ListTokensTool: Fetching URL: ${redactToken(url)}`);
 
         const response = await this.httpRequest(url, {
           method: 'GET',
@@ -130,12 +130,12 @@ export class ListTokensTool extends MapboxApiBasedTool<
           ? data
           : (data as { tokens?: unknown[] }).tokens || [];
 
-        // Validate tokens array against TokenObjectSchema with graceful fallback
-        const validatedTokens = this.validateOutput<unknown[]>(
-          TokenObjectSchema.array(),
-          tokens,
-          'ListTokensTool'
-        );
+        let validatedTokens;
+        try {
+          validatedTokens = TokenObjectSchema.array().parse(tokens);
+        } catch (validationError) {
+          return this.handleValidationError(validationError);
+        }
 
         allTokens.push(...validatedTokens);
         this.log(
@@ -149,26 +149,34 @@ export class ListTokensTool extends MapboxApiBasedTool<
         if (linkHeader) {
           const links = this.parseLinkHeader(linkHeader);
           if (links.next) {
-            // Ensure the next URL includes the access token
             const nextUrl = new URL(links.next);
-            if (!nextUrl.searchParams.has('access_token')) {
-              nextUrl.searchParams.append('access_token', accessToken);
-            }
-            const nextUrlString = nextUrl.toString();
-
-            if (shouldAutoPaginate) {
-              url = nextUrlString;
-              this.log('info', `ListTokensTool: Next page available: ${url}`);
+            // Reject cross-origin Link headers to prevent token exfiltration
+            const apiOrigin = new URL(ListTokensTool.mapboxApiEndpoint).origin;
+            if (nextUrl.origin !== apiOrigin) {
+              this.log(
+                'warning',
+                `ListTokensTool: Refusing cross-origin Link header: ${nextUrl.origin}`
+              );
             } else {
-              // For manual pagination, extract the start parameter from the next URL
-              const nextUrl = new URL(links.next);
-              const startParam = nextUrl.searchParams.get('start');
-              if (startParam) {
-                nextPageUrl = startParam;
-                this.log(
-                  'info',
-                  `ListTokensTool: Next page start token saved for manual pagination: ${nextPageUrl}`
-                );
+              // Ensure the next URL includes the access token
+              if (!nextUrl.searchParams.has('access_token')) {
+                nextUrl.searchParams.append('access_token', accessToken);
+              }
+              const nextUrlString = nextUrl.toString();
+
+              if (shouldAutoPaginate) {
+                url = nextUrlString;
+                this.log('info', 'ListTokensTool: Next page available');
+              } else {
+                // For manual pagination, extract the start parameter from the next URL
+                const startParam = nextUrl.searchParams.get('start');
+                if (startParam) {
+                  nextPageUrl = startParam;
+                  this.log(
+                    'info',
+                    'ListTokensTool: Next page start token saved for manual pagination'
+                  );
+                }
               }
             }
           }

src/tools/preview-style-tool/PreviewStyleTool.input.schema.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { styleIdSchema } from '../shared/styleId.schema.js';
 
 export const PreviewStyleSchema = z.object({
-  styleId: z.string().describe('Style ID to preview'),
+  styleId: styleIdSchema.describe('Style ID to preview'),
   accessToken: z
     .string()
     .startsWith(

src/tools/preview-style-tool/PreviewStyleTool.ts

@@ -74,7 +74,7 @@ export class PreviewStyleTool extends BaseTool<typeof PreviewStyleSchema> {
     const hashFragment =
       hashParams.length > 0 ? `#${hashParams.join('/')}` : '';
 
-    const url = `${MapboxApiBasedTool.mapboxApiEndpoint}styles/v1/${userName}/${input.styleId}.html?${params.toString()}${hashFragment}`;
+    const url = `${MapboxApiBasedTool.mapboxApiEndpoint}styles/v1/${encodeURIComponent(userName)}/${encodeURIComponent(input.styleId)}.html?${params.toString()}${hashFragment}`;
 
     // Build content array with URL
     const content: CallToolResult['content'] = [
@@ -86,7 +86,7 @@ export class PreviewStyleTool extends BaseTool<typeof PreviewStyleSchema> {
 
     // Add MCP-UI resource (for legacy MCP-UI clients)
     const uiResource = createUIResource({
-      uri: `ui://mapbox/preview-style/${userName}/${input.styleId}`,
+      uri: `ui://mapbox/preview-style/${encodeURIComponent(userName)}/${encodeURIComponent(input.styleId)}`,
       content: {
         type: 'externalUrl',
         iframeUrl: url

src/tools/retrieve-style-tool/RetrieveStyleTool.input.schema.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { styleIdSchema } from '../shared/styleId.schema.js';
 
 export const RetrieveStyleSchema = z.object({
-  styleId: z.string().describe('Style ID to retrieve')
+  styleId: styleIdSchema.describe('Style ID to retrieve')
 });
 
 export type RetrieveStyleInput = z.infer<typeof RetrieveStyleSchema>;