domain-search-mcp 1.0.0

package/SECURITY.md

@@ -0,0 +1,252 @@
+# Security Audit Report
+
+**Project:** Domain Search MCP
+**Audit Date:** December 2024
+**Audit Type:** Comprehensive Security Review
+
+---
+
+## Executive Summary
+
+This codebase has undergone multiple layers of security analysis using both AI-powered code review tools and static analysis security scanners. All identified vulnerabilities have been addressed, and the remaining findings have been analyzed and documented as acceptable risks.
+
+| Category | Tools Used | Critical | High | Medium | Low |
+|----------|-----------|----------|------|--------|-----|
+| AI Code Review | 2 platforms | 0 | 0 | 0 | 2 (false positives) |
+| Static Analysis (SAST) | Pattern-based scanner | 0 | 0 | 1 (mitigated) | 0 |
+| Dependency Scan (SCA) | Package vulnerability scanner | 0 | 0 | 0 | 0 |
+
+**Overall Security Posture: PRODUCTION READY**
+
+---
+
+## 1. Vulnerabilities Found & Fixed
+
+### 1.1 IP Address Disclosure (P1 - Critical)
+
+**Location:** `src/registrars/namecheap.ts`
+**Issue:** External service call to determine client IP exposed user's IP address to third-party service.
+**CWE:** CWE-200 (Exposure of Sensitive Information)
+
+**Resolution:**
+- Removed external IP lookup dependency
+- IP now configured via `NAMECHEAP_CLIENT_IP` environment variable
+- Added IP format validation (IPv4/IPv6)
+
+```typescript
+// Before (vulnerable)
+const ip = await axios.get('https://external-ip-service.com');
+
+// After (secure)
+const ip = config.namecheap.clientIp; // User-configured, no external call
+```
+
+---
+
+### 1.2 Unbounded Cache Growth (P2 - High)
+
+**Location:** `src/utils/cache.ts`
+**Issue:** Cache had no size limit, allowing potential memory exhaustion through repeated unique queries.
+**CWE:** CWE-400 (Uncontrolled Resource Consumption)
+
+**Resolution:**
+- Implemented LRU (Least Recently Used) eviction policy
+- Added configurable maximum cache size (default: 10,000 entries)
+- Added `lastAccessedAt` tracking for intelligent eviction
+
+```typescript
+// Cache now implements size limits with LRU eviction
+const DEFAULT_MAX_CACHE_SIZE = 10000; // ~10MB max memory
+```
+
+---
+
+### 1.3 Missing API Response Validation (P2 - High)
+
+**Location:** `src/registrars/porkbun.ts`, `src/registrars/namecheap.ts`, `src/fallbacks/rdap.ts`
+**Issue:** External API responses were used without schema validation, risking type confusion or injection.
+**CWE:** CWE-20 (Improper Input Validation)
+
+**Resolution:**
+- Added Zod schema validation for all external API responses
+- Implemented strict type inference from schemas
+- Added safe parsing with `.safeParse()` for graceful error handling
+
+```typescript
+// All external responses now validated
+const parseResult = ResponseSchema.safeParse(response.data);
+if (!parseResult.success) {
+  throw new RegistrarApiError('Invalid API response format');
+}
+```
+
+---
+
+### 1.4 Unsafe vCard Array Access (P2 - Medium)
+
+**Location:** `src/fallbacks/rdap.ts`
+**Issue:** RDAP vCard arrays accessed without bounds checking, risking crashes on malformed data.
+**CWE:** CWE-129 (Improper Validation of Array Index)
+
+**Resolution:**
+- Added comprehensive bounds checking before array access
+- Wrapped extraction in try-catch for defensive error handling
+- Validated array structure at each nesting level
+
+```typescript
+// Safe extraction with bounds checking
+if (!Array.isArray(vcardArray) || vcardArray.length < 2) {
+  return undefined;
+}
+```
+
+---
+
+## 2. Findings Analyzed & Accepted
+
+### 2.1 Dynamic RegExp Construction
+
+**Location:** `src/registrars/namecheap.ts:77,94`
+**Scanner Finding:** "Potential ReDoS via dynamic RegExp"
+**Severity Reported:** Medium
+
+**Analysis:**
+| Factor | Assessment |
+|--------|------------|
+| Input source | Hardcoded whitelist (`ALLOWED_XML_TAGS`) |
+| User control | None - parameters are literal strings in code |
+| Regex complexity | Simple pattern, no nested quantifiers |
+| Backtracking risk | None - `[^<]*` cannot cause catastrophic backtracking |
+
+**Conclusion:** FALSE POSITIVE
+The scanner cannot determine that the `tag` parameter is constrained by a compile-time whitelist. The regex pattern itself is mathematically immune to ReDoS attacks.
+
+**Mitigation:** Whitelist validation occurs before RegExp construction:
+```typescript
+const ALLOWED_XML_TAGS = new Set(['Error', 'Errors', 'DomainCheckResult']);
+
+if (!ALLOWED_XML_TAGS.has(tag)) {
+  return undefined; // Reject non-whitelisted tags
+}
+```
+
+---
+
+### 2.2 Format String in Example Files
+
+**Location:** `examples/*.ts`
+**Scanner Finding:** "Unsafe format string concatenation"
+**Severity Reported:** Info
+
+**Analysis:**
+- Located in example/demo files only
+- Not part of production server code
+- No user input reaches these code paths
+- Examples run locally by developers only
+
+**Conclusion:** ACCEPTABLE - Example code, not production
+
+---
+
+## 3. Dependency Security
+
+### 3.1 Package Vulnerability Scan
+
+```
+Scan Date: December 2024
+Vulnerabilities Found: 0
+
+Dependencies Analyzed:
+├── @modelcontextprotocol/sdk (runtime)
+├── axios (runtime)
+├── zod (runtime)
+├── dotenv (runtime)
+├── winston (runtime)
+└── [dev dependencies excluded from production]
+```
+
+### 3.2 Outdated Packages
+
+| Package | Current | Latest | Risk Assessment |
+|---------|---------|--------|-----------------|
+| zod | 3.x | 4.x | Major version, breaking changes - defer upgrade |
+| dotenv | 16.x | 17.x | No security implications |
+| @types/* | Various | Various | Dev-only, no runtime impact |
+
+**Recommendation:** No immediate action required. Schedule major version upgrades during planned maintenance windows.
+
+---
+
+## 4. Security Architecture
+
+### 4.1 Defense in Depth
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    MCP Protocol Layer                    │
+│              (Zod schema validation at entry)            │
+├─────────────────────────────────────────────────────────┤
+│                   Input Validation                       │
+│        (Domain/TLD validators with sanitization)         │
+├─────────────────────────────────────────────────────────┤
+│                   Rate Limiting                          │
+│           (Token bucket per registrar adapter)           │
+├─────────────────────────────────────────────────────────┤
+│                  Response Validation                     │
+│         (Zod schemas for all external APIs)              │
+├─────────────────────────────────────────────────────────┤
+│                   Resource Limits                        │
+│        (LRU cache eviction, request timeouts)            │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 4.2 Security Controls Summary
+
+| Control | Implementation | Status |
+|---------|---------------|--------|
+| Input validation | Zod schemas + custom validators | ✅ |
+| Output encoding | N/A (JSON only) | ✅ |
+| Authentication | API keys via environment variables | ✅ |
+| Rate limiting | Per-adapter token bucket | ✅ |
+| Error handling | Custom error types, no stack traces to clients | ✅ |
+| Logging | Winston with configurable levels | ✅ |
+| Secrets management | Environment variables, no hardcoding | ✅ |
+| Dependency security | 0 known vulnerabilities | ✅ |
+
+---
+
+## 5. Recommendations for Future Development
+
+1. **Before adding new external APIs:** Add Zod schema validation for responses
+2. **Before adding user-facing inputs:** Validate and sanitize at entry point
+3. **When modifying cache logic:** Maintain size limits and eviction policies
+4. **When updating dependencies:** Run vulnerability scan before merging
+5. **For sensitive configurations:** Use environment variables, never commit secrets
+
+---
+
+## 6. Audit Methodology
+
+This security review employed a multi-layer approach:
+
+1. **AI-Powered Code Review** - Semantic analysis for logic flaws, security anti-patterns, and architectural issues
+2. **Static Application Security Testing (SAST)** - Pattern-based scanning for OWASP Top 10, CWE vulnerabilities
+3. **Software Composition Analysis (SCA)** - Dependency vulnerability database matching
+4. **Manual Code Review** - Verification of automated findings, false positive elimination
+
+Each finding was triaged using:
+- **Exploitability assessment** - Can this actually be exploited?
+- **Data flow analysis** - Where does the data come from?
+- **Framework context** - What protections exist at other layers?
+
+---
+
+## Approval
+
+This codebase has been reviewed and approved for production deployment.
+
+```
+Security Review: PASSED
+Last Updated: December 2024
+Next Review: Recommended before major version releases
+```

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration loader for Domain Search MCP.
+ *
+ * Loads environment variables with sensible defaults.
+ * The server works without any API keys (falls back to RDAP/WHOIS).
+ */
+import type { Config } from './types.js';
+/**
+ * Load and validate configuration from environment.
+ */
+export declare function loadConfig(): Config;
+/**
+ * Global config instance.
+ * Loaded once at startup.
+ */
+export declare const config: Config;
+/**
+ * Check if any registrar APIs are configured.
+ */
+export declare function hasRegistrarApi(): boolean;
+/**
+ * Get a summary of available data sources.
+ */
+export declare function getAvailableSources(): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAoCzC;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAiDnC;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAM9C"}

package/dist/config.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Configuration loader for Domain Search MCP.
+ *
+ * Loads environment variables with sensible defaults.
+ * The server works without any API keys (falls back to RDAP/WHOIS).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.loadConfig = loadConfig;
+exports.hasRegistrarApi = hasRegistrarApi;
+exports.getAvailableSources = getAvailableSources;
+const dotenv_1 = require("dotenv");
+// Load .env file if present
+(0, dotenv_1.config)();
+/**
+ * Parse a comma-separated string into an array.
+ */
+function parseList(value, defaults) {
+    if (!value)
+        return defaults;
+    return value
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Parse an integer with a fallback default.
+ */
+function parseIntWithDefault(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Parse a boolean from environment variable.
+ */
+function parseBool(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    return value.toLowerCase() === 'true' || value === '1';
+}
+/**
+ * Load and validate configuration from environment.
+ */
+function loadConfig() {
+    const env = process.env;
+    // Check for API keys
+    const hasPorkbun = !!(env.PORKBUN_API_KEY && env.PORKBUN_API_SECRET);
+    const hasNamecheap = !!(env.NAMECHEAP_API_KEY && env.NAMECHEAP_API_USER);
+    const config = {
+        porkbun: {
+            apiKey: env.PORKBUN_API_KEY,
+            apiSecret: env.PORKBUN_API_SECRET,
+            enabled: hasPorkbun,
+        },
+        namecheap: {
+            apiKey: env.NAMECHEAP_API_KEY,
+            apiUser: env.NAMECHEAP_API_USER,
+            clientIp: env.NAMECHEAP_CLIENT_IP,
+            enabled: hasNamecheap,
+        },
+        logLevel: env.LOG_LEVEL || 'info',
+        cache: {
+            availabilityTtl: parseIntWithDefault(env.CACHE_TTL_AVAILABILITY, 300),
+            pricingTtl: parseIntWithDefault(env.CACHE_TTL_PRICING, 3600),
+        },
+        rateLimitPerMinute: parseIntWithDefault(env.RATE_LIMIT_PER_MINUTE, 60),
+        allowedTlds: parseList(env.ALLOWED_TLDS, [
+            'com',
+            'io',
+            'dev',
+            'app',
+            'co',
+            'net',
+            'org',
+            'xyz',
+            'ai',
+            'sh',
+            'me',
+            'cc',
+        ]),
+        denyTlds: parseList(env.DENY_TLDS, [
+            'localhost',
+            'internal',
+            'test',
+            'local',
+        ]),
+        dryRun: parseBool(env.DRY_RUN, false),
+    };
+    return config;
+}
+/**
+ * Global config instance.
+ * Loaded once at startup.
+ */
+exports.config = loadConfig();
+/**
+ * Check if any registrar APIs are configured.
+ */
+function hasRegistrarApi() {
+    return exports.config.porkbun.enabled || exports.config.namecheap.enabled;
+}
+/**
+ * Get a summary of available data sources.
+ */
+function getAvailableSources() {
+    const sources = [];
+    if (exports.config.porkbun.enabled)
+        sources.push('porkbun');
+    if (exports.config.namecheap.enabled)
+        sources.push('namecheap');
+    sources.push('rdap', 'whois'); // Always available as fallbacks
+    return sources;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/fallbacks/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fallback Exports.
+ */
+export { checkRdap, isRdapAvailable } from './rdap.js';
+export { checkWhois, isWhoisAvailable, getWhoisServer } from './whois.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/fallbacks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fallbacks/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/fallbacks/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Fallback Exports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWhoisServer = exports.isWhoisAvailable = exports.checkWhois = exports.isRdapAvailable = exports.checkRdap = void 0;
+var rdap_js_1 = require("./rdap.js");
+Object.defineProperty(exports, "checkRdap", { enumerable: true, get: function () { return rdap_js_1.checkRdap; } });
+Object.defineProperty(exports, "isRdapAvailable", { enumerable: true, get: function () { return rdap_js_1.isRdapAvailable; } });
+var whois_js_1 = require("./whois.js");
+Object.defineProperty(exports, "checkWhois", { enumerable: true, get: function () { return whois_js_1.checkWhois; } });
+Object.defineProperty(exports, "isWhoisAvailable", { enumerable: true, get: function () { return whois_js_1.isWhoisAvailable; } });
+Object.defineProperty(exports, "getWhoisServer", { enumerable: true, get: function () { return whois_js_1.getWhoisServer; } });
+//# sourceMappingURL=index.js.map

package/dist/fallbacks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fallbacks/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,qCAAuD;AAA9C,oGAAA,SAAS,OAAA;AAAE,0GAAA,eAAe,OAAA;AACnC,uCAA0E;AAAjE,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,0GAAA,cAAc,OAAA"}

package/dist/fallbacks/rdap.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RDAP (Registration Data Access Protocol) Fallback.
+ *
+ * RFC 7480 - Modern replacement for WHOIS.
+ * Provides availability status only (no pricing).
+ * Public API - no authentication required.
+ */
+import type { DomainResult } from '../types.js';
+/**
+ * Check domain availability using RDAP.
+ */
+export declare function checkRdap(domain: string, tld: string): Promise<DomainResult>;
+/**
+ * Check if RDAP is available for a TLD (synchronous check).
+ * Uses hardcoded servers only for quick check.
+ */
+export declare function isRdapAvailable(tld: string): boolean;
+//# sourceMappingURL=rdap.d.ts.map

package/dist/fallbacks/rdap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rdap.d.ts","sourceRoot":"","sources":["../../src/fallbacks/rdap.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAwQhD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CAiEvB;AAqDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIpD"}