Merge pull request #57 from IPGeolocation/release/v1.0.19-security-posture

Release v1.0.19 security posture hardening

Author: Sheharyar-Malik

Dockerfile

@@ -22,4 +22,4 @@ RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
 COPY --from=build /app/dist ./dist
 COPY manifest.json server.json LICENSE README.md ./
 
-ENTRYPOINT ["node", "/app/dist/index.js"]
+ENTRYPOINT ["node", "/app/dist/cli.js"]

README.md

@@ -16,7 +16,7 @@ Works with Claude Desktop, Cursor, Windsurf, VS Code, Codex, Cline, Glama, and a
 | Item | Value |
 |------|-------|
 | Package | `ipgeolocation-io-mcp` |
-| Version | `1.0.17` |
+| Version | `1.0.19` |
 | Transport | `stdio` |
 | Node.js | `>=18` |
 
@@ -605,21 +605,24 @@ The text answers below show what a client might say. Exact wording depends on th
 
 ## Error Codes
 
-All tools return structured errors instead of crashing the server.
+All tools return structured errors instead of crashing the server. API errors include the upstream status/message plus a `guidance` field so MCP clients can tell the user what to check next instead of only repeating the upstream response.
 
 | Code | Meaning |
 |------|---------|
 | `400` | Bad parameters, invalid date/time format, missing coordinate pair, or unsupported input |
 | `401` | Missing/invalid API key, free plan calling a paid tool, or non-English `lang` on free plan |
 | `404` | Resource not found (e.g., ASN does not exist) |
 | `405` | Method or subscription restriction from the upstream API |
+| `413` | POST body is larger than the upstream API allows |
+| `415` | POST request is missing the required `application/json` content type |
 | `423` | Bogon or private IP (`10.x.x.x`, `192.168.x.x`, etc.) |
 | `429` | Rate limit, daily credit limit, or account quota exceeded |
-| `499` | Upstream validation error or unsupported query |
+| `499` | Client-side request or connection timeout was too short |
+| `5xx` | Upstream API server-side error |
 | `502` | Server could not reach the upstream API |
 | `504` | Upstream API timed out |
 
-Exact status codes can vary by endpoint and request mode. If an upstream endpoint returns a different error, the server passes it through with a structured message.
+Exact status codes can vary by endpoint and request mode. If an upstream endpoint returns a status outside this table, the server does not guess the cause. It passes the upstream status and message through with `category: "undocumented_api_error"` and adds guidance for the MCP client to explain the response as an undocumented upstream status without inventing a cause.
 
 ## How It Works
 
@@ -640,6 +643,7 @@ At runtime:
 Tools that return stable data (not current-time lookups) cache their responses in process memory. Repeated lookups are faster and don't use additional credits. Client retries don't generate duplicate API calls.
 
 - Process-level cache, not client or model memory
+- Cache entries are scoped by API key, so separate MCP sessions do not share cached upstream data
 - Default TTL: 5 minutes (`300000` ms)
 - Cache resets when the server process stops
 - Cache misses on TTL expiry, changed parameters, or `force_refresh: true`

SECURITY.md

@@ -23,6 +23,7 @@ If you discover a security vulnerability, please report it responsibly:
 - The API key is read from the `IPGEOLOCATION_API_KEY` environment variable or injected per-session via the MCP runtime config.
 - The key is never logged, cached to disk, or included in error messages.
 - The key is transmitted only to `https://api.ipgeolocation.io` over HTTPS.
+- In-memory response cache entries are scoped by an API-key hash so different runtime-config sessions do not share cached upstream data.
 
 ### Network Access
 

manifest.json

@@ -169,5 +169,5 @@
       "required": true
     }
   },
-  "version": "1.0.18"
+  "version": "1.0.19"
 }

package-lock.json

@@ -20,9 +20,10 @@
   "scripts": {
     "build": "tsc && printf '%s\\n' '#!/usr/bin/env node' | cat - dist/cli.js > dist/cli.js.tmp && mv dist/cli.js.tmp dist/cli.js && chmod +x dist/cli.js",
     "prepare:mpak": "node scripts/prepare-mpak-package.mjs",
-    "test": "npm run test:unit && npm run test:integration",
+    "test": "npm run test:unit && npm run test:integration && npm run test:redteam",
     "test:unit": "npm run build && node --test --test-concurrency=1 tests/client.test.mjs tests/response.test.mjs tests/validation.test.mjs",
     "test:integration": "npm run build && node --test --test-concurrency=1 tests/tools.integration.test.mjs tests/mcp.protocol.test.mjs",
+    "test:redteam": "npm run build && node --test --test-concurrency=1 tests/redteam.security.test.mjs",
     "test:live": "npm run test:live:free && npm run test:live:paid",
     "test:live:free": "npm run build && node tests/live.smoke.mjs free",
     "test:live:paid": "npm run build && node tests/live.smoke.mjs paid",
@@ -90,5 +91,5 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   },
-  "version": "1.0.18"
+  "version": "1.0.19"
 }

package.json

@@ -29,7 +29,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "ipgeolocation-io-mcp",
-      "version": "1.0.18",
+      "version": "1.0.19",
       "transport": {
         "type": "stdio"
       },
@@ -45,5 +45,5 @@
       ]
     }
   ],
-  "version": "1.0.18"
+  "version": "1.0.19"
 }

server.json

@@ -2,9 +2,16 @@ import {
   getConfiguredApiKey,
   getRequestTimeoutMs,
 } from "./config.js";
+import { redactSensitiveText } from "./redaction.js";
 
 const API_BASE = "https://api.ipgeolocation.io";
 const MAX_UPSTREAM_ERROR_CHARS = 4000;
+const UPSTREAM_ERROR_MESSAGE_KEYS = [
+  "message",
+  "error",
+  "detail",
+  "description",
+];
 
 export function getApiKey(): string {
   const apiKey = getConfiguredApiKey();
@@ -46,13 +53,65 @@ async function fetchWithTimeout(
 
     throw new ApiError(
       502,
-      `502: Failed to reach upstream API (${error instanceof Error ? error.message : String(error)})`
+      `502: Failed to reach upstream API (${redactSensitiveText(
+        error instanceof Error ? error.message : String(error)
+      )})`
     );
   } finally {
     clearTimeout(timeout);
   }
 }
 
+function parseUpstreamErrorMessage(text: string, fallback: string): string {
+  if (!text) {
+    return fallback;
+  }
+
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (typeof parsed === "string") {
+      return parsed;
+    }
+
+    if (typeof parsed === "object" && parsed !== null) {
+      for (const key of UPSTREAM_ERROR_MESSAGE_KEYS) {
+        const value = (parsed as Record<string, unknown>)[key];
+        if (typeof value === "string" && value.trim()) {
+          return value;
+        }
+      }
+    }
+  } catch {
+    // Keep the raw body below when the upstream error is not JSON.
+  }
+
+  return text;
+}
+
+async function throwUpstreamResponseError(
+  response: Response,
+  fallback = response.statusText
+): Promise<never> {
+  let message: string;
+  try {
+    const text = await response.text();
+    message = parseUpstreamErrorMessage(text, fallback);
+  } catch {
+    message = fallback;
+  }
+
+  message = redactSensitiveText(message);
+
+  if (message.length > MAX_UPSTREAM_ERROR_CHARS) {
+    message = `${message.slice(
+      0,
+      MAX_UPSTREAM_ERROR_CHARS
+    )}... [truncated upstream error body]`;
+  }
+
+  throw new ApiError(response.status, `${response.status}: ${message}`);
+}
+
 async function request(
   path: string,
   params: Record<string, string | undefined> = {},
@@ -88,22 +147,7 @@ async function request(
   const response = await fetchWithTimeout(url.toString(), fetchOptions);
 
   if (!response.ok) {
-    let message: string;
-    try {
-      const text = await response.text();
-      message = text || response.statusText;
-    } catch {
-      message = response.statusText;
-    }
-
-    if (message.length > MAX_UPSTREAM_ERROR_CHARS) {
-      message = `${message.slice(
-        0,
-        MAX_UPSTREAM_ERROR_CHARS
-      )}... [truncated upstream error body]`;
-    }
-
-    throw new ApiError(response.status, `${response.status}: ${message}`);
+    await throwUpstreamResponseError(response);
   }
 
   try {
@@ -132,7 +176,10 @@ export async function getIpGeolocation(params: {
 export async function getMyIp(): Promise<string> {
   const response = await fetchWithTimeout(`${API_BASE}/v3/getip`);
   if (!response.ok) {
-    throw new ApiError(response.status, "Failed to retrieve IP address");
+    await throwUpstreamResponseError(
+      response,
+      "Failed to retrieve IP address"
+    );
   }
   let data: { ip: string };
   try {

src/client.ts

@@ -30,7 +30,7 @@ const toolSelectionInstructionParts = [
 const TOOL_SELECTION_INSTRUCTIONS = toolSelectionInstructionParts.join(" ");
 
 export const configSchema = z.object({
-  apiKey: z.string().describe("Your IPGeolocation.io API key"),
+  apiKey: z.string().min(1).describe("Your IPGeolocation.io API key"),
 });
 
 type SessionConfig = z.infer<typeof configSchema>;
@@ -63,7 +63,7 @@ export function createMcpServer(
 ): McpServer {
   const server = new McpServer({
     name: "ipgeolocation-io-mcp",
-    version: "1.0.17",
+    version: "1.0.19",
   }, {
     instructions: TOOL_SELECTION_INSTRUCTIONS,
   });

src/index.ts

@@ -0,0 +1,58 @@
+import { getConfiguredApiKey } from "./config.js";
+
+const REDACTED_API_KEY = "[REDACTED_API_KEY]";
+const REDACTED_TOKEN = "[REDACTED_TOKEN]";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function uniqueSecretVariants(secret: string): string[] {
+  const variants = new Set<string>();
+  const trimmed = secret.trim();
+
+  if (!trimmed) {
+    return [];
+  }
+
+  variants.add(trimmed);
+  variants.add(encodeURIComponent(trimmed));
+  variants.add(encodeURIComponent(encodeURIComponent(trimmed)));
+
+  return [...variants].sort((a, b) => b.length - a.length);
+}
+
+export function redactSensitiveText(text: string): string {
+  let redacted = text;
+
+  const configuredApiKey = getConfiguredApiKey();
+  if (configuredApiKey) {
+    for (const variant of uniqueSecretVariants(configuredApiKey)) {
+      redacted = redacted.replace(
+        new RegExp(escapeRegExp(variant), "g"),
+        REDACTED_API_KEY
+      );
+    }
+  }
+
+  redacted = redacted
+    .replace(
+      /([?&](?:apiKey|apikey|api_key|api-key)=)[^&#\s"']+/gi,
+      `$1${REDACTED_API_KEY}`
+    )
+    .replace(
+      /((?:apiKey|apikey|api_key|api-key)%3D)(?:%[0-9A-Fa-f]{2}|[^&#\s"'])+/gi,
+      `$1${REDACTED_API_KEY}`
+    )
+    .replace(
+      /((?:"(?:apiKey|apikey|api_key|api-key)"|(?:apiKey|apikey|api_key|api-key))\s*[:=]\s*["']?)([^"',\s}]+)(["']?)/gi,
+      `$1${REDACTED_API_KEY}$3`
+    )
+    .replace(
+      /(authorization\s*[:=]\s*bearer\s+)[^\s,"']+/gi,
+      `$1${REDACTED_TOKEN}`
+    )
+    .replace(/\bbearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_TOKEN}`);
+
+  return redacted;
+}