@cosmocoder/mcp-web-docs 1.0.0

package/build/util/logger.test.js

@@ -0,0 +1,46 @@
+import { logger } from './logger.js';
+describe('Logger', () => {
+    describe('API surface', () => {
+        it.each(['debug', 'info', 'warn', 'error'])('should have %s method', (method) => {
+            expect(typeof logger[method]).toBe('function');
+        });
+    });
+    describe('methods do not throw', () => {
+        it.each(['debug', 'info', 'warn', 'error'])('should not throw when calling %s with string', (method) => {
+            expect(() => logger[method]('Test message')).not.toThrow();
+        });
+        it('should not throw when calling with multiple arguments', () => {
+            expect(() => logger.error('Multiple', 'arguments', 123, true)).not.toThrow();
+        });
+        it('should not throw when calling with Error object', () => {
+            const error = new Error('Test error');
+            expect(() => logger.error('Got error:', error)).not.toThrow();
+        });
+        it('should not throw when calling with nested object', () => {
+            const obj = { nested: { deep: { value: true } } };
+            expect(() => logger.info('Object:', obj)).not.toThrow();
+        });
+        it('should not throw when calling with circular reference', () => {
+            const circular = {};
+            circular.self = circular;
+            expect(() => logger.error('Circular:', circular)).not.toThrow();
+        });
+        it('should not throw when calling with null/undefined', () => {
+            expect(() => logger.info('Values:', null, undefined)).not.toThrow();
+        });
+        it('should not throw when calling with empty string', () => {
+            expect(() => logger.info('')).not.toThrow();
+        });
+        it('should not throw when calling with unicode', () => {
+            expect(() => logger.info('Unicode: 你好世界 🌍')).not.toThrow();
+        });
+        it('should not throw when calling with special characters', () => {
+            expect(() => logger.info('Special: <>&"\' \n\t')).not.toThrow();
+        });
+        it('should not throw when calling with very long message', () => {
+            const longMessage = 'a'.repeat(10000);
+            expect(() => logger.info(longMessage)).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=logger.test.js.map

package/build/util/logger.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.js","sourceRoot":"","sources":["../../src/util/logger.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE;IACtB,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC,CAAC,uBAAuB,EAAE,CAAC,MAAM,EAAE,EAAE;YACvF,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;QACpC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC,CAAC,8CAA8C,EAAE,CAAC,MAAM,EAAE,EAAE;YAC9G,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC7D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAC/D,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC/E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;YACzD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC1D,MAAM,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC1D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAC/D,MAAM,QAAQ,GAA4B,EAAE,CAAC;YAC7C,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC;YACzB,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAClE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACtE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;YACzD,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC9C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;YACpD,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAC9D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAC/D,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QAClE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;YAC9D,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACvD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/build/util/security.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Security utilities for mcp-web-docs
+ * Handles encryption, input sanitization, and validation
+ */
+import { z } from 'zod';
+/**
+ * Encrypt sensitive data using AES-256-GCM
+ * @param plaintext - Data to encrypt
+ * @returns Encrypted data as base64 string with embedded IV, salt, and auth tag
+ */
+export declare function encryptData(plaintext: string): string;
+/**
+ * Decrypt data encrypted with encryptData
+ * @param encryptedData - Base64 encoded encrypted data
+ * @returns Decrypted plaintext
+ */
+export declare function decryptData(encryptedData: string): string;
+/**
+ * Escape special characters for LanceDB filter expressions
+ * Prevents SQL/filter injection attacks
+ * @param value - User-provided value to escape
+ * @returns Escaped value safe for use in filter expressions
+ */
+export declare function escapeFilterValue(value: string): string;
+/**
+ * Validate and sanitize a URL for safe usage
+ * Prevents SSRF attacks by blocking private/internal networks
+ * @param urlString - URL to validate
+ * @returns Validated URL object
+ * @throws Error if URL is invalid or points to private network
+ */
+export declare function validatePublicUrl(urlString: string): URL;
+/**
+ * Check if a regex pattern is safe (not vulnerable to ReDoS)
+ * Uses safe-regex2 from https://github.com/fastify/safe-regex2
+ * @param pattern - Regex pattern string to check
+ * @returns true if pattern is safe, false if potentially dangerous
+ */
+export declare function isSafeRegex(pattern: string): boolean;
+/**
+ * Create a safe RegExp from user input with ReDoS protection
+ * @param pattern - User-provided regex pattern
+ * @param flags - Optional regex flags
+ * @returns RegExp object
+ * @throws Error if pattern is unsafe or invalid
+ */
+export declare function createSafeRegex(pattern: string, flags?: string): RegExp;
+/**
+ * Schema for browser storage state (cookies and localStorage)
+ */
+export declare const StorageStateSchema: z.ZodObject<{
+    cookies: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        domain: z.ZodString;
+        path: z.ZodString;
+        expires: z.ZodOptional<z.ZodNumber>;
+        httpOnly: z.ZodOptional<z.ZodBoolean>;
+        secure: z.ZodOptional<z.ZodBoolean>;
+        sameSite: z.ZodOptional<z.ZodEnum<{
+            Strict: "Strict";
+            Lax: "Lax";
+            None: "None";
+        }>>;
+    }, z.core.$strip>>;
+    origins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        origin: z.ZodString;
+        localStorage: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ValidatedStorageState = z.infer<typeof StorageStateSchema>;
+/**
+ * Schema for stored session data
+ */
+export declare const StoredSessionSchema: z.ZodObject<{
+    domain: z.ZodString;
+    storageState: z.ZodString;
+    createdAt: z.ZodString;
+    browser: z.ZodEnum<{
+        chromium: "chromium";
+        chrome: "chrome";
+        firefox: "firefox";
+        webkit: "webkit";
+        edge: "edge";
+    }>;
+    version: z.ZodLiteral<2>;
+}, z.core.$strip>;
+/** Validated stored session type */
+export type ValidatedStoredSession = z.infer<typeof StoredSessionSchema>;
+/**
+ * Schema for GitHub API file response
+ */
+export declare const GitHubFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        dir: "dir";
+    }>;
+    url: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const GitHubFilesArraySchema: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        dir: "dir";
+    }>;
+    url: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type ValidatedGitHubFile = z.infer<typeof GitHubFileSchema>;
+/**
+ * Safely parse JSON with schema validation
+ * @param jsonString - JSON string to parse
+ * @param schema - Zod schema to validate against
+ * @returns Validated and typed data
+ * @throws Error if JSON is invalid or doesn't match schema
+ */
+export declare function safeJsonParse<T>(jsonString: string, schema: z.ZodSchema<T>): T;
+/**
+ * Generate a secure hash for cache keys or identifiers
+ * @param input - String to hash
+ * @returns SHA-256 hash as hex string
+ */
+export declare function secureHash(input: string): string;
+/**
+ * Schema for add_documentation tool arguments
+ */
+export declare const AddDocumentationArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    pathPrefix: z.ZodOptional<z.ZodString>;
+    auth: z.ZodOptional<z.ZodObject<{
+        requiresAuth: z.ZodOptional<z.ZodBoolean>;
+        browser: z.ZodOptional<z.ZodEnum<{
+            chromium: "chromium";
+            chrome: "chrome";
+            firefox: "firefox";
+            webkit: "webkit";
+            edge: "edge";
+        }>>;
+        loginUrl: z.ZodOptional<z.ZodString>;
+        loginSuccessPattern: z.ZodOptional<z.ZodString>;
+        loginSuccessSelector: z.ZodOptional<z.ZodString>;
+        loginTimeoutSecs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AddDocumentationArgs = z.infer<typeof AddDocumentationArgsSchema>;
+/**
+ * Schema for authenticate tool arguments
+ */
+export declare const AuthenticateArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        chrome: "chrome";
+        firefox: "firefox";
+        webkit: "webkit";
+        edge: "edge";
+    }>>;
+    loginUrl: z.ZodOptional<z.ZodString>;
+    loginTimeoutSecs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuthenticateArgs = z.infer<typeof AuthenticateArgsSchema>;
+/**
+ * Schema for clear_auth tool arguments
+ */
+export declare const ClearAuthArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+export type ClearAuthArgs = z.infer<typeof ClearAuthArgsSchema>;
+/**
+ * Schema for search_documentation tool arguments
+ */
+export declare const SearchDocumentationArgsSchema: z.ZodObject<{
+    query: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SearchDocumentationArgs = z.infer<typeof SearchDocumentationArgsSchema>;
+/**
+ * Schema for reindex_documentation tool arguments
+ */
+export declare const ReindexDocumentationArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+export type ReindexDocumentationArgs = z.infer<typeof ReindexDocumentationArgsSchema>;
+/**
+ * Schema for delete_documentation tool arguments
+ */
+export declare const DeleteDocumentationArgsSchema: z.ZodObject<{
+    url: z.ZodString;
+    clearAuth: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DeleteDocumentationArgs = z.infer<typeof DeleteDocumentationArgsSchema>;
+/**
+ * Validate MCP tool arguments against a schema
+ * @param args - Raw arguments from MCP request
+ * @param schema - Zod schema to validate against
+ * @returns Validated and typed arguments
+ * @throws Error with user-friendly message if validation fails
+ */
+export declare function validateToolArgs<T>(args: Record<string, unknown> | undefined, schema: z.ZodSchema<T>): T;
+/**
+ * Sanitize an error message for safe return to clients.
+ * Removes sensitive information like file paths, credentials, and system details.
+ * @param error - The error to sanitize
+ * @returns A safe error message
+ */
+export declare function sanitizeErrorMessage(error: unknown): string;
+/**
+ * Redact sensitive information from log messages.
+ * Use this before logging any data that might contain credentials.
+ * @param data - The data to sanitize for logging
+ * @returns Sanitized string safe for logging
+ */
+export declare function redactForLogging(data: unknown): string;
+/**
+ * Result of prompt injection detection
+ */
+export interface PromptInjectionResult {
+    /** Whether any injection patterns were detected */
+    hasInjection: boolean;
+    /** Highest severity level found */
+    maxSeverity: 'high' | 'medium' | 'low' | 'none';
+    /** List of detected patterns */
+    detections: Array<{
+        severity: 'high' | 'medium' | 'low';
+        description: string;
+        match: string;
+    }>;
+}
+/**
+ * Detect potential prompt injection patterns in content using vard.
+ * Uses the vard package for robust, performant detection of:
+ * - Instruction overrides ("ignore all previous instructions")
+ * - Role manipulation ("you are now a...")
+ * - Delimiter injection ([SYSTEM], <|im_start|>)
+ * - System prompt leaks ("reveal your instructions")
+ * - Encoding attacks (base64, homoglyphs, unicode escapes)
+ *
+ * NOTE: Code blocks are stripped before detection to avoid false positives
+ * from code examples (especially common in AI/LLM documentation).
+ *
+ * @param content - The content to scan
+ * @returns Detection results with severity and matched patterns
+ * @see https://github.com/andersmyrmel/vard
+ */
+export declare function detectPromptInjection(content: string): PromptInjectionResult;
+/**
+ * Marker to wrap content indicating it's from an external untrusted source.
+ * This helps AI assistants understand the content should be treated with caution.
+ */
+export declare const EXTERNAL_CONTENT_MARKER: {
+    prefix: string;
+    suffix: string;
+};
+/**
+ * Wrap content with external source markers to indicate it's from an untrusted source.
+ * @param content - The content to wrap
+ * @param source - Optional source URL for attribution
+ * @returns Content wrapped with safety markers
+ */
+export declare function wrapExternalContent(content: string, source?: string): string;
+/**
+ * Add injection warnings to content if prompt injection patterns are detected.
+ * @param content - The content to check
+ * @param detectionResult - Result from detectPromptInjection
+ * @returns Content with warnings prepended if injections detected
+ */
+export declare function addInjectionWarnings(content: string, detectionResult: PromptInjectionResult): string;
+/**
+ * Result of login page detection
+ */
+export interface LoginPageDetectionResult {
+    /** Whether this appears to be a login page */
+    isLoginPage: boolean;
+    /** Confidence level (0-1) based on number of indicators matched */
+    confidence: number;
+    /** Detected reasons (for logging/debugging) */
+    reasons: string[];
+}
+/**
+ * Detect if a URL looks like a login/authentication page.
+ * @param url - The URL to check
+ * @returns Whether the URL pattern suggests a login page
+ */
+export declare function isLoginPageUrl(url: string): boolean;
+/**
+ * Detect if page content suggests a login page.
+ * This is a heuristic check - it counts how many login-related
+ * indicators are present in the content.
+ *
+ * @param content - The page's text content
+ * @param url - The page URL (for additional URL-based detection)
+ * @returns Detection result with confidence score
+ */
+export declare function detectLoginPage(content: string, url: string): LoginPageDetectionResult;
+/**
+ * Error thrown when authentication session has expired.
+ * This allows callers to handle session expiration gracefully.
+ */
+export declare class SessionExpiredError extends Error {
+    readonly detectedUrl: string;
+    readonly expectedUrl: string;
+    readonly detectionResult: LoginPageDetectionResult;
+    constructor(message: string, expectedUrl: string, detectedUrl: string, detectionResult: LoginPageDetectionResult);
+}