@open-loyalty/mcp-server 1.0.3 → 1.3.1

package/dist/tools/webhook.js

@@ -1,49 +1,143 @@
 import { z } from "zod";
+import { isIP } from "net";
 import { apiGet, apiPost, apiPut, apiDelete } from "../client/http.js";
 import { formatApiError } from "../utils/errors.js";
-import { getConfig } from "../config.js";
+import { getStoreCode } from "../config.js";
+/**
+ * Check if an IP address is private, loopback, link-local, or otherwise internal.
+ * Blocks IPv4 and IPv6 private ranges to prevent SSRF attacks.
+ */
+function isPrivateIP(ip) {
+    const normalizedIP = ip.toLowerCase();
+    // IPv4 private/reserved ranges
+    if (normalizedIP.startsWith("10.") || // 10.0.0.0/8 private
+        normalizedIP.startsWith("192.168.") || // 192.168.0.0/16 private
+        normalizedIP.match(/^172\.(1[6-9]|2[0-9]|3[0-1])\./) || // 172.16.0.0/12 private
+        normalizedIP.startsWith("127.") || // 127.0.0.0/8 loopback
+        normalizedIP.startsWith("169.254.") || // 169.254.0.0/16 link-local
+        normalizedIP === "0.0.0.0" || // Unspecified
+        normalizedIP.startsWith("100.64.") || // 100.64.0.0/10 carrier-grade NAT
+        normalizedIP.match(/^100\.(6[4-9]|[7-9][0-9]|1[0-1][0-9]|12[0-7])\./) // 100.64-127.x.x
+    ) {
+        return true;
+    }
+    // IPv6 private/reserved ranges
+    if (normalizedIP === "::1" || // Loopback
+        normalizedIP === "::" || // Unspecified
+        normalizedIP.startsWith("fc") || // fc00::/7 unique local (fc00-fdff)
+        normalizedIP.startsWith("fd") || // fc00::/7 unique local (fc00-fdff)
+        normalizedIP.startsWith("fe80:") || // fe80::/10 link-local
+        normalizedIP.startsWith("::ffff:127.") || // IPv4-mapped loopback
+        normalizedIP.startsWith("::ffff:10.") || // IPv4-mapped private
+        normalizedIP.startsWith("::ffff:192.168.") || // IPv4-mapped private
+        normalizedIP.match(/^::ffff:172\.(1[6-9]|2[0-9]|3[0-1])\./) // IPv4-mapped private
+    ) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if a hostname points to an internal DNS name.
+ * Blocks common internal TLDs and patterns.
+ */
+function isInternalHostname(hostname) {
+    const lowerHostname = hostname.toLowerCase();
+    // Block localhost variants
+    if (lowerHostname === "localhost" ||
+        lowerHostname.endsWith(".localhost") ||
+        lowerHostname.endsWith(".local") ||
+        lowerHostname.endsWith(".internal") ||
+        lowerHostname.endsWith(".lan") ||
+        lowerHostname.endsWith(".home") ||
+        lowerHostname.endsWith(".corp") ||
+        lowerHostname.endsWith(".intranet")) {
+        return true;
+    }
+    // Block cloud metadata hostnames
+    if (lowerHostname === "metadata.google.internal" ||
+        lowerHostname === "metadata" ||
+        lowerHostname.endsWith(".metadata") ||
+        lowerHostname === "instance-data" ||
+        lowerHostname.endsWith(".amazonaws.com") && lowerHostname.includes("metadata")) {
+        return true;
+    }
+    return false;
+}
+// SSRF protection: validate webhook URLs are external HTTPS endpoints
+function isValidWebhookUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Must be HTTPS
+        if (parsed.protocol !== "https:") {
+            return false;
+        }
+        const hostname = parsed.hostname.toLowerCase();
+        // Block internal hostnames
+        if (isInternalHostname(hostname)) {
+            return false;
+        }
+        // If hostname is an IP address, validate it directly
+        if (isIP(hostname)) {
+            return !isPrivateIP(hostname);
+        }
+        // Block cloud metadata IP
+        if (hostname === "169.254.169.254") {
+            return false;
+        }
+        // For DNS hostnames, we can't resolve at validation time (sync function),
+        // but we've blocked common internal patterns above.
+        // Note: Full DNS rebinding protection would require async DNS resolution,
+        // which could be added if this becomes a concern in production.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const webhookUrlSchema = z.string()
+    .url("Must be a valid URL")
+    .refine(isValidWebhookUrl, "URL must be an external HTTPS endpoint (no localhost, private IPs, or metadata endpoints)");
 // Input Schemas
 export const WebhookListInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     page: z.number().optional().describe("Page number (default: 1)."),
     perPage: z.number().optional().describe("Items per page (default: 25)."),
     eventName: z.string().optional().describe("Filter by event name."),
     url: z.string().optional().describe("Filter by URL."),
 };
 export const WebhookCreateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     eventName: z.string().describe("Event name to subscribe to. Use webhook_events to discover available events."),
-    url: z.string().describe("URL to receive webhook events."),
+    url: webhookUrlSchema.describe("HTTPS URL to receive webhook events. Must be an external endpoint (no localhost or private IPs)."),
     headers: z.array(z.object({
         headerName: z.string().describe("Header name."),
         headerValue: z.string().describe("Header value."),
     })).optional().describe("Custom headers to include in webhook requests."),
 };
 export const WebhookGetInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     webhookSubscriptionId: z.string().describe("The webhook subscription ID (UUID) to retrieve."),
 };
 export const WebhookUpdateInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     webhookSubscriptionId: z.string().describe("The webhook subscription ID (UUID) to update."),
     eventName: z.string().optional().describe("Event name to subscribe to."),
-    url: z.string().optional().describe("URL to receive webhook events."),
+    url: webhookUrlSchema.optional().describe("HTTPS URL to receive webhook events. Must be an external endpoint (no localhost or private IPs)."),
     headers: z.array(z.object({
         headerName: z.string().describe("Header name."),
         headerValue: z.string().describe("Header value."),
     })).optional().describe("Custom headers to include in webhook requests."),
 };
 export const WebhookDeleteInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     webhookSubscriptionId: z.string().describe("The webhook subscription ID (UUID) to delete."),
 };
 export const WebhookEventsInputSchema = {
-    storeCode: z.string().optional().describe("Store code. If not provided, uses the default store code from configuration."),
+    storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
 };
 // Handler functions
 export async function webhookList(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const params = new URLSearchParams();
     if (input.page)
         params.append("_page", String(input.page));
@@ -60,12 +154,11 @@ export async function webhookList(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_list");
+        throw formatApiError(error, "ol_webhook_list");
     }
 }
 export async function webhookCreate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const payload = {
         eventName: input.eventName,
         url: input.url,
@@ -78,23 +171,21 @@ export async function webhookCreate(input) {
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_create");
+        throw formatApiError(error, "ol_webhook_create");
     }
 }
 export async function webhookGet(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         const response = await apiGet(`/${storeCode}/webhook/subscription/${input.webhookSubscriptionId}`);
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_get");
+        throw formatApiError(error, "ol_webhook_get");
     }
 }
 export async function webhookUpdate(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     const payload = {};
     if (input.eventName)
         payload.eventName = input.eventName;
@@ -106,65 +197,76 @@ export async function webhookUpdate(input) {
         await apiPut(`/${storeCode}/webhook/subscription/${input.webhookSubscriptionId}`, { webhookSubscription: payload });
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_update");
+        throw formatApiError(error, "ol_webhook_update");
     }
 }
 export async function webhookDelete(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         await apiDelete(`/${storeCode}/webhook/subscription/${input.webhookSubscriptionId}`);
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_delete");
+        throw formatApiError(error, "ol_webhook_delete");
     }
 }
 export async function webhookEvents(input) {
-    const config = getConfig();
-    const storeCode = input.storeCode || config.defaultStoreCode;
+    const storeCode = getStoreCode(input.storeCode);
     try {
         const response = await apiGet(`/${storeCode}/webhook/event`);
         return response;
     }
     catch (error) {
-        throw formatApiError(error, "openloyalty_webhook_events");
+        throw formatApiError(error, "ol_webhook_events");
     }
 }
 // Tool definitions
 export const webhookToolDefinitions = [
     {
-        name: "openloyalty_webhook_list",
+        name: "ol_webhook_list",
+        title: "List Webhook Subscriptions",
         description: "List webhook subscriptions with optional filtering. Returns paginated list of subscriptions with webhookSubscriptionId, eventName, url, and createdAt.",
+        readOnly: true,
         inputSchema: WebhookListInputSchema,
         handler: webhookList,
     },
     {
-        name: "openloyalty_webhook_create",
+        name: "ol_webhook_create",
+        title: "Create Webhook Subscription",
         description: "Create a new webhook subscription to receive event notifications. Returns webhookSubscriptionId on success. Use webhook_events to discover available event types before creating subscriptions.",
+        readOnly: false,
         inputSchema: WebhookCreateInputSchema,
         handler: webhookCreate,
     },
     {
-        name: "openloyalty_webhook_get",
+        name: "ol_webhook_get",
+        title: "Get Webhook Subscription Details",
         description: "Get full webhook subscription details including headers configuration.",
+        readOnly: true,
         inputSchema: WebhookGetInputSchema,
         handler: webhookGet,
     },
     {
-        name: "openloyalty_webhook_update",
+        name: "ol_webhook_update",
+        title: "Update Webhook Subscription",
         description: "Update a webhook subscription. Can update eventName, url, and headers. Returns void on success (204 No Content).",
+        readOnly: false,
         inputSchema: WebhookUpdateInputSchema,
         handler: webhookUpdate,
     },
     {
-        name: "openloyalty_webhook_delete",
+        name: "ol_webhook_delete",
+        title: "Delete Webhook Subscription (Permanent)",
         description: "Delete a webhook subscription. Returns void on success (204 No Content). The subscription will stop receiving events immediately.",
+        readOnly: false,
+        destructive: true,
         inputSchema: WebhookDeleteInputSchema,
         handler: webhookDelete,
     },
     {
-        name: "openloyalty_webhook_events",
+        name: "ol_webhook_events",
+        title: "List Available Webhook Events",
         description: "Get available webhook event types. Returns list of event names that can be used when creating webhook subscriptions. Use this to discover available events before creating subscriptions.",
+        readOnly: true,
         inputSchema: WebhookEventsInputSchema,
         handler: webhookEvents,
     },