security: restrict doc tool URL allowlist and block access_token params

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## Unreleased
 
+- security: restrict document tool URL allowlist to documentation hosts and block access_token params (#34)
 - chore: upgrade @opentelemetry/\* packages to latest minor versions (#TBD)
 
 ## 0.3.0 - 2026-04-15

src/tools/batch-get-documents-tool/BatchGetDocumentsTool.ts

@@ -11,10 +11,28 @@ import {
   BatchGetDocumentsInput
 } from './BatchGetDocumentsTool.input.schema.js';
 
+// Explicit allowlist of hostnames this docs tool is permitted to fetch.
+// api.mapbox.com is intentionally excluded — it is a live API that requires
+// auth tokens, not a documentation host. Allowing it would let callers poison
+// the shared cache with token-authorized private responses under no-token keys.
+const ALLOWED_DOC_HOSTNAMES = new Set([
+  'docs.mapbox.com',
+  'mapbox.com',
+  'docs.tilestream.net'
+]);
+
 function isMapboxUrl(url: string): boolean {
   try {
     const { hostname } = new URL(url);
-    return hostname === 'mapbox.com' || hostname.endsWith('.mapbox.com');
+    return ALLOWED_DOC_HOSTNAMES.has(hostname);
+  } catch {
+    return false;
+  }
+}
+
+function hasAccessToken(url: string): boolean {
+  try {
+    return new URL(url).searchParams.has('access_token');
   } catch {
     return false;
   }
@@ -54,7 +72,20 @@ export class BatchGetDocumentsTool extends BaseTool<
         content: [
           {
             type: 'text',
-            text: `Invalid URLs: only mapbox.com URLs are supported. Invalid: ${invalidUrls.join(', ')}`
+            text: `Invalid URLs: only mapbox.com documentation URLs are supported. Invalid: ${invalidUrls.join(', ')}`
+          }
+        ],
+        isError: true
+      };
+    }
+
+    const tokenUrls = input.urls.filter(hasAccessToken);
+    if (tokenUrls.length > 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid URLs: URLs must not contain access_token. Invalid: ${tokenUrls.join(', ')}`
           }
         ],
         isError: true

src/tools/get-document-tool/GetDocumentTool.ts

@@ -11,10 +11,28 @@ import {
   GetDocumentInput
 } from './GetDocumentTool.input.schema.js';
 
+// Explicit allowlist of hostnames this docs tool is permitted to fetch.
+// api.mapbox.com is intentionally excluded — it is a live API that requires
+// auth tokens, not a documentation host. Allowing it would let callers poison
+// the shared cache with token-authorized private responses under no-token keys.
+const ALLOWED_DOC_HOSTNAMES = new Set([
+  'docs.mapbox.com',
+  'mapbox.com',
+  'docs.tilestream.net'
+]);
+
 function isMapboxUrl(url: string): boolean {
   try {
     const { hostname } = new URL(url);
-    return hostname === 'mapbox.com' || hostname.endsWith('.mapbox.com');
+    return ALLOWED_DOC_HOSTNAMES.has(hostname);
+  } catch {
+    return false;
+  }
+}
+
+function hasAccessToken(url: string): boolean {
+  try {
+    return new URL(url).searchParams.has('access_token');
   } catch {
     return false;
   }
@@ -45,7 +63,19 @@ export class GetDocumentTool extends BaseTool<typeof GetDocumentSchema> {
         content: [
           {
             type: 'text',
-            text: `Invalid URL: only mapbox.com URLs are supported. Received: ${input.url}`
+            text: `Invalid URL: only mapbox.com documentation URLs are supported. Received: ${input.url}`
+          }
+        ],
+        isError: true
+      };
+    }
+
+    if (hasAccessToken(input.url)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid URL: URLs must not contain access_token. Received: ${input.url}`
           }
         ],
         isError: true

test/tools/batch-get-documents-tool/BatchGetDocumentsTool.test.ts

@@ -124,6 +124,52 @@ describe('BatchGetDocumentsTool', () => {
       expect(result.isError).toBe(true);
       expect(httpRequest).not.toHaveBeenCalled();
     });
+
+    it('rejects api.mapbox.com URLs', async () => {
+      const httpRequest = vi.fn();
+      const tool = new BatchGetDocumentsTool({ httpRequest });
+
+      const result = await tool.run({
+        urls: ['https://api.mapbox.com/styles/v1/owner/styleId']
+      });
+
+      expect(result.isError).toBe(true);
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+
+    it('rejects URLs containing access_token', async () => {
+      const httpRequest = vi.fn();
+      const tool = new BatchGetDocumentsTool({ httpRequest });
+
+      const result = await tool.run({
+        urls: ['https://docs.mapbox.com/page?access_token=pk.secret']
+      });
+
+      expect(result.isError).toBe(true);
+      expect((result.content[0] as { text: string }).text).toMatch(
+        /access_token/
+      );
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+
+    it('blocks cache poisoning: tokenized URL cannot prime cache for no-token URL', async () => {
+      // Even if somehow both URLs passed validation (they do not), this test
+      // documents the expected behavior: private data must not leak.
+      // In practice the access_token check above prevents this entirely.
+      const httpRequest = vi.fn().mockResolvedValue(makeResponse('private'));
+      const tool = new BatchGetDocumentsTool({ httpRequest });
+
+      // Attempt the poisoning using an api.mapbox.com URL — must be rejected
+      const poisonResult = await tool.run({
+        urls: [
+          'https://api.mapbox.com/styles/v1/owner/id?access_token=secret',
+          'https://api.mapbox.com/styles/v1/owner/id'
+        ]
+      });
+      expect(poisonResult.isError).toBe(true);
+      expect(httpRequest).not.toHaveBeenCalled();
+      expect(docCache.size).toBe(0);
+    });
   });
 
   describe('HTTP errors', () => {

test/tools/get-document-tool/GetDocumentTool.test.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Mapbox, Inc.
+// Licensed under the MIT License.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GetDocumentTool } from '../../../src/tools/get-document-tool/GetDocumentTool.js';
+import { docCache } from '../../../src/utils/docCache.js';
+
+beforeEach(() => {
+  docCache.clear();
+});
+
+function makeResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: {
+      'content-type': 'text/plain',
+      'content-length': String(Buffer.byteLength(body, 'utf8'))
+    }
+  });
+}
+
+describe('GetDocumentTool', () => {
+  describe('URL validation', () => {
+    it('rejects non-mapbox URLs', async () => {
+      const httpRequest = vi.fn();
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({ url: 'https://evil.com/page' });
+
+      expect(result.isError).toBe(true);
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+
+    it('rejects api.mapbox.com URLs', async () => {
+      const httpRequest = vi.fn();
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({
+        url: 'https://api.mapbox.com/styles/v1/owner/styleId'
+      });
+
+      expect(result.isError).toBe(true);
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+
+    it('rejects URLs containing access_token', async () => {
+      const httpRequest = vi.fn();
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({
+        url: 'https://docs.mapbox.com/page?access_token=pk.secret'
+      });
+
+      expect(result.isError).toBe(true);
+      expect((result.content[0] as { text: string }).text).toMatch(
+        /access_token/
+      );
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+
+    it('allows docs.mapbox.com URLs', async () => {
+      const httpRequest = vi.fn().mockResolvedValue(makeResponse('content'));
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({ url: 'https://docs.mapbox.com/page' });
+
+      expect(result.isError).toBe(false);
+    });
+  });
+
+  describe('caching', () => {
+    it('returns cached content without an HTTP request', async () => {
+      docCache.set('https://docs.mapbox.com/page', 'cached content');
+      const httpRequest = vi.fn();
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({ url: 'https://docs.mapbox.com/page' });
+
+      expect(result.isError).toBe(false);
+      expect((result.content[0] as { text: string }).text).toBe(
+        'cached content'
+      );
+      expect(httpRequest).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('HTTP errors', () => {
+    it('returns an error on non-ok response', async () => {
+      const httpRequest = vi
+        .fn()
+        .mockResolvedValue(
+          new Response('Not Found', { status: 404, statusText: 'Not Found' })
+        );
+      const tool = new GetDocumentTool({ httpRequest });
+
+      const result = await tool.run({ url: 'https://docs.mapbox.com/missing' });
+
+      expect(result.isError).toBe(true);
+      expect((result.content[0] as { text: string }).text).toMatch(
+        /Failed to fetch/
+      );
+    });
+  });
+});