mcp-wordpress 2.4.2 → 2.5.0

package/src/utils/streaming.ts

@@ -4,12 +4,13 @@
  */
 
 // Node.js streaming imports removed - not currently used but available for future enhancement
+import { sanitizeHtml } from "./validation/security.js";
 
 export interface StreamingOptions {
   batchSize?: number;
   delay?: number;
-  transformItem?: (item: any) => any;
-  filterItem?: (item: any) => boolean;
+  transformItem?: (item: unknown) => unknown;
+  filterItem?: (item: unknown) => boolean;
 }
 
 export interface StreamingResult<T> {
@@ -26,7 +27,7 @@ export interface StreamingResult<T> {
 export class DataStreamer<T> {
   private batchSize: number;
   private delay: number;
-  private transformItem: ((item: T) => any) | undefined;
+  private transformItem: ((item: T) => unknown) | undefined;
   private filterItem: ((item: T) => boolean) | undefined;
 
   constructor(options: StreamingOptions = {}) {
@@ -57,14 +58,14 @@ export class DataStreamer<T> {
 
       // Apply transformation if provided
       const transformedBatch = this.transformItem
-        ? processedBatch.map((item: any) => this.transformItem!(item))
+        ? processedBatch.map((item: unknown) => this.transformItem!(item as T))
         : processedBatch;
 
       processed += batch.length;
       const hasMore = processed < total;
 
       yield {
-        data: transformedBatch,
+        data: transformedBatch as U[],
         hasMore,
         cursor: hasMore ? String(i + this.batchSize) : undefined,
         total,
@@ -103,13 +104,13 @@ export class DataStreamer<T> {
 
       // Apply transformation if provided
       const transformedData = this.transformItem
-        ? processedData.map((item: any) => this.transformItem!(item))
+        ? processedData.map((item: unknown) => this.transformItem!(item as T))
         : processedData;
 
       totalProcessed += result.data.length;
 
       yield {
-        data: transformedData,
+        data: transformedData as U[],
         hasMore: result.hasMore,
         cursor: result.hasMore ? String(page + 1) : undefined,
         total: undefined, // Unknown for paginated results
@@ -138,33 +139,39 @@ export class WordPressDataStreamer {
    * Streams WordPress posts with author and taxonomy information
    */
   static async *streamPosts(
-    posts: any[],
+    posts: unknown[],
     options: {
       includeAuthor?: boolean;
       includeCategories?: boolean;
       includeTags?: boolean;
       batchSize?: number;
     } = {},
-  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
-    const streamer = new DataStreamer<any>({
+  ): AsyncGenerator<StreamingResult<unknown>, void, unknown> {
+    const streamer = new DataStreamer<unknown>({
       batchSize: options.batchSize || 20,
-      transformItem: (post) => ({
-        id: post.id,
-        title: post.title?.rendered || "Untitled",
-        excerpt: post.excerpt?.rendered
-          ? post.excerpt.rendered.replace(/<[^>]*>/g, "").substring(0, 150) + "..."
-          : "No excerpt",
-        status: post.status,
-        date: new Date(post.date).toLocaleDateString(),
-        link: post.link,
-        author: options.includeAuthor ? post.author : undefined,
-        categories: options.includeCategories ? post.categories : undefined,
-        tags: options.includeTags ? post.tags : undefined,
-      }),
-      filterItem: (post) => post.status !== "trash", // Filter out trashed posts
+      transformItem: (post) => {
+        const p = post as Record<string, unknown>;
+        const title = p.title as Record<string, unknown> | undefined;
+        const excerpt = p.excerpt as Record<string, unknown> | undefined;
+        return {
+          id: p.id,
+          title: title?.rendered || "Untitled",
+          excerpt: excerpt?.rendered ? sanitizeHtml(String(excerpt.rendered)).substring(0, 150) + "..." : "No excerpt",
+          status: p.status,
+          date: new Date(String(p.date)).toLocaleDateString(),
+          link: p.link,
+          author: options.includeAuthor ? p.author : undefined,
+          categories: options.includeCategories ? p.categories : undefined,
+          tags: options.includeTags ? p.tags : undefined,
+        };
+      },
+      filterItem: (post) => {
+        const p = post as Record<string, unknown>;
+        return p.status !== "trash";
+      }, // Filter out trashed posts
     });
 
-    const processor = async (batch: any[]) => {
+    const processor = async (batch: unknown[]) => {
       // Simulate processing time for large datasets
       await new Promise((resolve) => setTimeout(resolve, 10));
       return batch;
@@ -179,27 +186,32 @@ export class WordPressDataStreamer {
    * Streams WordPress users with role information
    */
   static async *streamUsers(
-    users: any[],
+    users: unknown[],
     options: {
       includeRoles?: boolean;
       includeCapabilities?: boolean;
       batchSize?: number;
     } = {},
-  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
-    const streamer = new DataStreamer<any>({
+  ): AsyncGenerator<StreamingResult<unknown>, void, unknown> {
+    const streamer = new DataStreamer<unknown>({
       batchSize: options.batchSize || 30,
-      transformItem: (user) => ({
-        id: user.id,
-        name: user.name || "No name",
-        username: user.slug || "unknown",
-        email: user.email || "No email",
-        roles: options.includeRoles ? user.roles : undefined,
-        capabilities: options.includeCapabilities ? Object.keys(user.capabilities || {}) : undefined,
-        registeredDate: user.registered_date ? new Date(user.registered_date).toLocaleDateString() : "Unknown",
-      }),
+      transformItem: (user) => {
+        const u = user as Record<string, unknown>;
+        return {
+          id: u.id,
+          name: u.name || "No name",
+          username: u.slug || "unknown",
+          email: u.email || "No email",
+          roles: options.includeRoles ? u.roles : undefined,
+          capabilities: options.includeCapabilities
+            ? Object.keys((u.capabilities as Record<string, unknown>) || {})
+            : undefined,
+          registeredDate: u.registered_date ? new Date(String(u.registered_date)).toLocaleDateString() : "Unknown",
+        };
+      },
     });
 
-    const processor = async (batch: any[]) => {
+    const processor = async (batch: unknown[]) => {
       // Add user processing logic here if needed
       return batch;
     };
@@ -213,35 +225,40 @@ export class WordPressDataStreamer {
    * Streams WordPress comments with moderation status
    */
   static async *streamComments(
-    comments: any[],
+    comments: unknown[],
     options: {
       includeAuthor?: boolean;
       includePost?: boolean;
       batchSize?: number;
     } = {},
-  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
-    const streamer = new DataStreamer<any>({
+  ): AsyncGenerator<StreamingResult<unknown>, void, unknown> {
+    const streamer = new DataStreamer<unknown>({
       batchSize: options.batchSize || 40,
-      transformItem: (comment) => ({
-        id: comment.id,
-        content: comment.content?.rendered
-          ? comment.content.rendered.replace(/<[^>]*>/g, "").substring(0, 200) + "..."
-          : "No content",
-        status: comment.status,
-        date: new Date(comment.date).toLocaleDateString(),
-        author: options.includeAuthor
-          ? {
-              name: comment.author_name,
-              email: comment.author_email,
-              url: comment.author_url,
-            }
-          : undefined,
-        post: options.includePost ? comment.post : undefined,
-      }),
-      filterItem: (comment) => comment.status !== "spam", // Filter out spam comments
+      transformItem: (comment) => {
+        const c = comment as Record<string, unknown>;
+        const content = c.content as Record<string, unknown> | undefined;
+        return {
+          id: c.id,
+          content: content?.rendered ? sanitizeHtml(String(content.rendered)).substring(0, 200) + "..." : "No content",
+          status: c.status,
+          date: new Date(String(c.date)).toLocaleDateString(),
+          author: options.includeAuthor
+            ? {
+                name: c.author_name,
+                email: c.author_email,
+                url: c.author_url,
+              }
+            : undefined,
+          post: options.includePost ? c.post : undefined,
+        };
+      },
+      filterItem: (comment) => {
+        const c = comment as Record<string, unknown>;
+        return c.status !== "spam";
+      }, // Filter out spam comments
     });
 
-    const processor = async (batch: any[]) => {
+    const processor = async (batch: unknown[]) => {
       // Add comment processing logic here if needed
       return batch;
     };
@@ -260,7 +277,7 @@ export class StreamingUtils {
    * Formats streaming results for display
    */
   static formatStreamingResponse(
-    results: StreamingResult<any>[],
+    results: StreamingResult<unknown>[],
     type: "posts" | "users" | "comments" | "media" = "posts",
   ): string {
     const allData = results.flatMap((result) => result.data);
@@ -290,12 +307,15 @@ export class StreamingUtils {
 
     // Format individual items
     allData.forEach((item, index) => {
-      response += `${index + 1}. **${item.title || item.name || item.content?.substring(0, 50) || "Item"}**\n`;
+      // Type-safe property access
+      const itemObj = item as Record<string, unknown>;
+      const title = itemObj.title || itemObj.name || (itemObj.content as string)?.substring(0, 50) || "Item";
+      response += `${index + 1}. **${title}**\n`;
 
-      if (item.excerpt) response += `   📝 ${item.excerpt}\n`;
-      if (item.email) response += `   📧 ${item.email}\n`;
-      if (item.status) response += `   🏷️ Status: ${item.status}\n`;
-      if (item.date) response += `   📅 Date: ${item.date}\n`;
+      if (itemObj.excerpt) response += `   📝 ${itemObj.excerpt}\n`;
+      if (itemObj.email) response += `   📧 ${itemObj.email}\n`;
+      if (itemObj.status) response += `   🏷️ Status: ${itemObj.status}\n`;
+      if (itemObj.date) response += `   📅 Date: ${itemObj.date}\n`;
 
       response += "\n";
     });
@@ -321,7 +341,6 @@ export class StreamingUtils {
 
     const results: T[] = [];
     let offset = 0;
-    let hasMore = true;
 
     // Initial load
     const initialBatch = await fetcher(offset, initialLoad);
@@ -333,11 +352,10 @@ export class StreamingUtils {
     }
 
     // Progressive loading
-    while (hasMore && results.length < maxItems) {
+    while (results.length < maxItems) {
       const batch = await fetcher(offset, batchSize);
 
       if (batch.length === 0) {
-        hasMore = false;
         break;
       }
 

package/src/utils/toolWrapper.ts

@@ -4,11 +4,13 @@
  */
 
 import { getErrorMessage } from "./error.js";
+import type { IWordPressClient } from '../types/client.js';
+import type { BaseToolParams } from '../types/tools.js';
 
 /**
  * Wrapper for tool methods that standardizes error handling
  */
-export function withErrorHandling<T extends any[], R>(
+export function withErrorHandling<T extends readonly unknown[], R>(
   operation: string,
   fn: (...args: T) => Promise<R>,
 ): (...args: T) => Promise<R> {
@@ -24,7 +26,7 @@ export function withErrorHandling<T extends any[], R>(
 /**
  * Wrapper for tool methods with validation
  */
-export function withValidation<T extends any[], R>(
+export function withValidation<T extends readonly unknown[], R>(
   operation: string,
   validator: (...args: T) => void,
   fn: (...args: T) => Promise<R>,
@@ -43,7 +45,7 @@ export function withValidation<T extends any[], R>(
  * Common validation functions
  */
 export const validators = {
-  requireSite: (client: any, params: any) => {
+  requireSite: (client: IWordPressClient | null | undefined, params: BaseToolParams) => {
     if (!client) {
       throw new Error("WordPress client is required");
     }
@@ -55,13 +57,13 @@ export const validators = {
     }
   },
 
-  requireNonEmpty: (value: any, fieldName: string) => {
+  requireNonEmpty: (value: unknown, fieldName: string) => {
     if (!value || (typeof value === "string" && value.trim() === "")) {
       throw new Error(`${fieldName} cannot be empty`);
     }
   },
 
-  requireFields: (params: any, fields: string[]) => {
+  requireFields: (params: Record<string, unknown>, fields: readonly string[]) => {
     for (const field of fields) {
       if (params[field] === undefined || params[field] === null) {
         throw new Error(`${field} is required`);
@@ -74,14 +76,10 @@ export const validators = {
  * Decorator for class methods to add error handling
  */
 export function errorHandler(operation: string) {
-  return function (
-    target: any,
-    propertyKey: string,
-    descriptor: PropertyDescriptor,
-  ) {
+  return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
     const originalMethod = descriptor.value;
 
-    descriptor.value = async function (...args: any[]) {
+    descriptor.value = async function (...args: unknown[]) {
       try {
         return await originalMethod.apply(this, args);
       } catch (error) {
@@ -103,7 +101,7 @@ export function formatSuccessResponse(content: string): string {
 /**
  * Helper to format error responses consistently
  */
-export function formatErrorResponse(operation: string, error: any): never {
+export function formatErrorResponse(operation: string, error: unknown): never {
   const message = getErrorMessage(error);
   throw new Error(`${operation}: ${message}`);
 }

package/src/utils/validation/core.ts

@@ -0,0 +1,108 @@
+/**
+ * Core Validation Utilities
+ *
+ * Basic validation functions for common data types including IDs, strings, and arrays.
+ * These validators form the foundation for more specific validation logic.
+ */
+
+import { WordPressAPIError } from "../../types/client.js";
+import { WordPressId, createWordPressId } from "../../types/enhanced.js";
+
+/**
+ * Validates and sanitizes numeric IDs with comprehensive edge case handling
+ * Returns branded WordPress ID type for enhanced type safety
+ */
+export function validateId(id: unknown, fieldName: string = "id"): WordPressId {
+  // Handle null/undefined
+  if (id === null || id === undefined) {
+    throw new WordPressAPIError(`${fieldName} is required`, 400, "MISSING_PARAMETER");
+  }
+
+  // Convert to string first to handle various input types
+  const strId = String(id).trim();
+
+  // Check for empty string after trim
+  if (strId === "") {
+    throw new WordPressAPIError(`${fieldName} cannot be empty`, 400, "INVALID_PARAMETER");
+  }
+
+  // Handle decimal inputs
+  if (strId.includes(".")) {
+    throw new WordPressAPIError(`${fieldName} must be a whole number, not a decimal`, 400, "INVALID_PARAMETER");
+  }
+
+  const numId = parseInt(strId, 10);
+
+  // Check for NaN
+  if (isNaN(numId)) {
+    throw new WordPressAPIError(`Invalid ${fieldName}: "${id}" is not a valid number`, 400, "INVALID_PARAMETER");
+  }
+
+  // Check for negative or zero
+  if (numId <= 0) {
+    throw new WordPressAPIError(
+      `Invalid ${fieldName}: must be a positive number (got ${numId})`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  // Check for max int32 limit (WordPress database limit)
+  if (numId > 2147483647) {
+    throw new WordPressAPIError(
+      `Invalid ${fieldName}: exceeds maximum allowed value (2147483647)`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  return createWordPressId(numId);
+}
+
+/**
+ * Validates string length within bounds
+ */
+export function validateString(
+  value: unknown,
+  fieldName: string,
+  minLength: number = 1,
+  maxLength: number = 1000,
+): string {
+  if (typeof value !== "string") {
+    throw new WordPressAPIError(`Invalid ${fieldName}: must be a string`, 400, "INVALID_PARAMETER");
+  }
+
+  const trimmed = value.trim();
+  if (trimmed.length < minLength || trimmed.length > maxLength) {
+    throw new WordPressAPIError(
+      `Invalid ${fieldName}: length must be between ${minLength} and ${maxLength} characters`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  return trimmed;
+}
+
+/**
+ * Validates arrays with size constraints and type safety
+ */
+export function validateArray<T>(value: unknown, fieldName: string, minItems: number = 0, maxItems: number = 100): T[] {
+  if (!Array.isArray(value)) {
+    throw new WordPressAPIError(`Invalid ${fieldName}: must be an array`, 400, "INVALID_PARAMETER");
+  }
+
+  if (value.length < minItems) {
+    throw new WordPressAPIError(`Invalid ${fieldName}: must have at least ${minItems} items`, 400, "INVALID_PARAMETER");
+  }
+
+  if (value.length > maxItems) {
+    throw new WordPressAPIError(
+      `Invalid ${fieldName}: cannot have more than ${maxItems} items`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  return value as T[];
+}

package/src/utils/validation/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Validation Utilities - Modular Export Index
+ *
+ * This module re-exports all validation functions from their focused modules
+ * for backward compatibility and convenient imports.
+ *
+ * @example
+ * ```typescript
+ * // Import all validators (backward compatible)
+ * import { validateId, validateUrl, validatePostParams } from "./utils/validation";
+ *
+ * // Or import from specific modules
+ * import { validateId } from "./utils/validation/core";
+ * import { validateUrl } from "./utils/validation/network";
+ * import { validatePostParams } from "./utils/validation/wordpress";
+ * ```
+ */
+
+// Core validators - basic data types
+export { validateId, validateString, validateArray } from "./core.js";
+
+// Security validators - file and content safety
+export { validateFilePath, validateFileSize, validateMimeType, sanitizeHtml } from "./security.js";
+
+// Network validators - URLs, emails, usernames
+export { validateUrl, validateEmail, validateUsername } from "./network.js";
+
+// WordPress-specific validators
+export { validatePostStatus, validateSearchQuery, validatePaginationParams, validatePostParams } from "./wordpress.js";
+
+// Rate limiting utilities
+export { RateLimiter, authRateLimiter } from "./rateLimit.js";
+
+// Re-export type dependencies for convenience
+export type { WordPressId } from "../../types/enhanced.js";
+export { WordPressAPIError } from "../../types/client.js";

package/src/utils/validation/network.ts

@@ -0,0 +1,132 @@
+/**
+ * Network Validation Utilities
+ *
+ * Validation functions for network-related data including URLs, email addresses,
+ * and username validation with security considerations.
+ */
+
+import { WordPressAPIError } from "../../types/client.js";
+import { config } from "../../config/Config.js";
+
+/**
+ * Validates and sanitizes URLs with enhanced edge case handling
+ */
+export function validateUrl(url: string, fieldName: string = "url"): string {
+  // Check for empty or whitespace-only URLs
+  const trimmedUrl = url.trim();
+  if (!trimmedUrl) {
+    throw new WordPressAPIError(`${fieldName} cannot be empty`, 400, "INVALID_PARAMETER");
+  }
+
+  // Remove trailing slashes for consistency
+  const cleanUrl = trimmedUrl.replace(/\/+$/, "");
+
+  // Check for common URL mistakes
+  if (!cleanUrl.match(/^https?:\/\//i)) {
+    throw new WordPressAPIError(
+      `Invalid ${fieldName}: must start with http:// or https:// (got "${cleanUrl}")`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  try {
+    const urlObj = new URL(cleanUrl);
+
+    // Only allow http and https protocols
+    if (!["http:", "https:"].includes(urlObj.protocol)) {
+      throw new WordPressAPIError(
+        `Invalid ${fieldName}: only HTTP and HTTPS protocols are allowed`,
+        400,
+        "INVALID_PARAMETER",
+      );
+    }
+
+    // Validate hostname
+    if (!urlObj.hostname || urlObj.hostname.length < 3) {
+      throw new WordPressAPIError(`Invalid ${fieldName}: hostname is missing or too short`, 400, "INVALID_PARAMETER");
+    }
+
+    // Check for localhost in production
+    if (config().app.isProduction && (urlObj.hostname === "localhost" || urlObj.hostname === "127.0.0.1")) {
+      throw new WordPressAPIError(
+        `Invalid ${fieldName}: localhost URLs are not allowed in production`,
+        400,
+        "INVALID_PARAMETER",
+      );
+    }
+
+    // Validate port if present
+    if (urlObj.port) {
+      const port = parseInt(urlObj.port);
+      if (port < 1 || port > 65535) {
+        throw new WordPressAPIError(
+          `Invalid ${fieldName}: port number must be between 1 and 65535`,
+          400,
+          "INVALID_PARAMETER",
+        );
+      }
+    }
+
+    return cleanUrl;
+  } catch (error) {
+    if (error instanceof WordPressAPIError) {
+      throw error;
+    }
+    throw new WordPressAPIError(`Invalid ${fieldName}: malformed URL "${cleanUrl}"`, 400, "INVALID_PARAMETER");
+  }
+}
+
+/**
+ * Validates email addresses
+ */
+export function validateEmail(email: string): string {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email)) {
+    throw new WordPressAPIError("Invalid email address format", 400, "INVALID_PARAMETER");
+  }
+  return email.toLowerCase();
+}
+
+/**
+ * Validates username format with enhanced security checks
+ */
+export function validateUsername(username: string): string {
+  // Trim and check for empty
+  const trimmed = username.trim();
+  if (!trimmed) {
+    throw new WordPressAPIError("Username cannot be empty", 400, "INVALID_PARAMETER");
+  }
+
+  // WordPress username rules: alphanumeric, space, underscore, hyphen, period, @ symbol
+  const usernameRegex = /^[a-zA-Z0-9 _.\-@]+$/;
+  if (!usernameRegex.test(trimmed)) {
+    throw new WordPressAPIError(
+      "Invalid username: can only contain letters, numbers, spaces, and _.-@ symbols",
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  // Length validation
+  if (trimmed.length < 3 || trimmed.length > 60) {
+    throw new WordPressAPIError(
+      `Invalid username: must be between 3 and 60 characters (got ${trimmed.length})`,
+      400,
+      "INVALID_PARAMETER",
+    );
+  }
+
+  // Check for consecutive spaces
+  if (/\s{2,}/.test(trimmed)) {
+    throw new WordPressAPIError("Invalid username: cannot contain consecutive spaces", 400, "INVALID_PARAMETER");
+  }
+
+  // Security: Prevent common problematic usernames
+  const blacklist = ["admin", "root", "wordpress", "wp-admin", "administrator"];
+  if (blacklist.includes(trimmed.toLowerCase())) {
+    throw new WordPressAPIError(`Username "${trimmed}" is reserved and cannot be used`, 400, "RESERVED_USERNAME");
+  }
+
+  return trimmed;
+}

package/src/utils/validation/rateLimit.ts

@@ -0,0 +1,54 @@
+/**
+ * Rate Limiting Utilities
+ *
+ * Simple in-memory rate limiting for authentication and API requests.
+ * For production, consider using Redis or similar distributed cache.
+ */
+
+import { WordPressAPIError } from "../../types/client.js";
+
+/**
+ * Rate limiting tracker (simple in-memory implementation)
+ * For production, use Redis or similar
+ */
+class RateLimiter {
+  private attempts: Map<string, { count: number; resetTime: number }> = new Map();
+
+  constructor(
+    private maxAttempts: number = 5,
+    private windowMs: number = 60000, // 1 minute
+  ) {}
+
+  check(identifier: string): void {
+    const now = Date.now();
+    const record = this.attempts.get(identifier);
+
+    if (!record || record.resetTime < now) {
+      this.attempts.set(identifier, {
+        count: 1,
+        resetTime: now + this.windowMs,
+      });
+      return;
+    }
+
+    if (record.count >= this.maxAttempts) {
+      const waitTime = Math.ceil((record.resetTime - now) / 1000);
+      throw new WordPressAPIError(
+        `Rate limit exceeded. Please wait ${waitTime} seconds before trying again.`,
+        429,
+        "RATE_LIMIT_EXCEEDED",
+      );
+    }
+
+    record.count++;
+  }
+
+  reset(identifier: string): void {
+    this.attempts.delete(identifier);
+  }
+}
+
+// Export a default rate limiter for authentication attempts
+export const authRateLimiter = new RateLimiter(5, 300000); // 5 attempts per 5 minutes
+
+export { RateLimiter };