documentation-hub 5.7.2

package/src/utils/textSanitizer.ts

@@ -0,0 +1,162 @@
+/**
+ * Text Sanitization Utilities
+ *
+ * Handles defensive cleanup of corrupted text from docxmlater framework.
+ *
+ * PROBLEM CONTEXT:
+ * ─────────────────
+ * The docxmlater Hyperlink.getText() method may return text containing XML markup
+ * when the underlying Run object contains corrupted data. This happens when:
+ * - Hyperlink runs have malformed XML structures
+ * - Text nodes contain embedded XML tags like <w:t xml:space="preserve">
+ * - Document was previously corrupted or modified externally
+ *
+ * EXPECTED BEHAVIOR:
+ * The Run() constructor auto-cleans by default (cleanXmlFromText: true)
+ * But Hyperlink.getText() doesn't apply the same cleanup.
+ *
+ * SOLUTION:
+ * Apply defensive XML tag removal to all hyperlink text extraction.
+ * This prevents XML corruption from propagating through the system.
+ *
+ * EXAMPLE:
+ * Input:  "Important Information<w:t xml:space=\"preserve\">1"
+ * Output: "Important Information1"
+ */
+
+/**
+ * Remove XML markup from text
+ *
+ * Removes any XML-like tags: <w:t>, <w:t xml:space="preserve">, etc.
+ * Safe to call on any text - if no tags present, returns unchanged.
+ *
+ * @param text - The text that may contain XML markup
+ * @returns The text with XML tags removed
+ *
+ * @example
+ * ```typescript
+ * sanitizeHyperlinkText("Hello<w:t>World</w:t>")
+ * // Returns: "HelloWorld"
+ *
+ * sanitizeHyperlinkText("Clean text")
+ * // Returns: "Clean text"
+ *
+ * sanitizeHyperlinkText("Text with<w:t xml:space=\"preserve\">space")
+ * // Returns: "Text withspace"
+ * ```
+ */
+export function sanitizeHyperlinkText(text: string): string {
+  if (!text) return '';
+
+  // Remove all XML tags: <...> patterns
+  // This matches:
+  // - Simple tags: <w:t>
+  // - Tags with attributes: <w:t xml:space="preserve">
+  // - Self-closing tags: <br/>
+  // - Any other XML markup
+  const cleaned = text.replace(/<[^>]+>/g, '');
+
+  return cleaned;
+}
+
+/**
+ * Sanitize display text with optional fallback
+ *
+ * If the text is empty after sanitization, optionally falls back to a default.
+ * Useful for hyperlink display text that might be corrupted to empty strings.
+ *
+ * @param text - The text to sanitize
+ * @param fallback - Optional fallback if result is empty
+ * @returns The sanitized text, or fallback if empty
+ *
+ * @example
+ * ```typescript
+ * // With fallback
+ * sanitizeHyperlinkTextWithFallback("<w:t>", "Click here")
+ * // Returns: "Click here"
+ *
+ * // Without fallback
+ * sanitizeHyperlinkTextWithFallback("Normal Text")
+ * // Returns: "Normal Text"
+ * ```
+ */
+export function sanitizeHyperlinkTextWithFallback(text: string, fallback?: string): string {
+  const sanitized = sanitizeHyperlinkText(text);
+
+  if (!sanitized && fallback) {
+    return fallback;
+  }
+
+  return sanitized;
+}
+
+/**
+ * Check if text appears to contain XML corruption
+ *
+ * Useful for diagnostic logging and determining if corruption occurred.
+ *
+ * @param text - The text to check
+ * @returns true if the text contains XML-like tags
+ *
+ * @example
+ * ```typescript
+ * isTextCorrupted("Normal text")
+ * // Returns: false
+ *
+ * isTextCorrupted("Text<w:t>with tags</w:t>")
+ * // Returns: true
+ * ```
+ */
+export function isTextCorrupted(text: string): boolean {
+  if (!text) return false;
+  return /<[^>]+>/.test(text);
+}
+
+/**
+ * Sanitize array of hyperlink texts
+ *
+ * Applies sanitization to multiple texts efficiently.
+ *
+ * @param texts - Array of texts to sanitize
+ * @returns Array of sanitized texts
+ *
+ * @example
+ * ```typescript
+ * sanitizeHyperlinkTexts([
+ *   "Text<w:t>1</w:t>",
+ *   "Normal text",
+ *   "Another<tag>corrupted</tag>"
+ * ])
+ * // Returns: ["Text1", "Normal text", "Anothercorrupted"]
+ * ```
+ */
+export function sanitizeHyperlinkTexts(texts: string[]): string[] {
+  return texts.map(sanitizeHyperlinkText);
+}
+
+/**
+ * Replace en-dashes and em-dashes with regular hyphens
+ *
+ * Normalizes typographic dashes to standard ASCII hyphens:
+ * - En-dash (U+2013, –) -> Hyphen (U+002D, -)
+ * - Em-dash (U+2014, —) -> Hyphen (U+002D, -)
+ *
+ * @param text - The text that may contain en-dashes or em-dashes
+ * @returns The text with dashes normalized to hyphens
+ *
+ * @example
+ * ```typescript
+ * normalizeEnDashesToHyphens("2020–2024")
+ * // Returns: "2020-2024"
+ *
+ * normalizeEnDashesToHyphens("Hello—World")
+ * // Returns: "Hello-World"
+ *
+ * normalizeEnDashesToHyphens("Normal text with - hyphens")
+ * // Returns: "Normal text with - hyphens" (unchanged)
+ * ```
+ */
+export function normalizeEnDashesToHyphens(text: string): string {
+  if (!text) return '';
+  return text.replace(/[\u2013\u2014]/g, '-');
+}

package/src/utils/urlHelpers.ts

@@ -0,0 +1,304 @@
+/**
+ * URL Helper Utilities
+ *
+ * Provides functions for sanitizing, validating, and fixing common URL encoding issues.
+ * This is critical for Azure Logic Apps URLs which often come with encoded query parameters.
+ */
+
+/**
+ * Sanitize a URL by decoding common encoding issues
+ *
+ * Fixes three common URL encoding problems:
+ * 1. Unicode escapes: \u0026 → &
+ * 2. HTML entities: & → &
+ * 3. URL encoding: %26 → &
+ *
+ * @param url - The URL to sanitize (may contain encoded characters)
+ * @returns Sanitized URL with properly decoded query parameters
+ *
+ * @example
+ * // Azure Logic App URL with Unicode escapes
+ * const encoded = 'https://api.com?v=1\u0026sp=/triggers';
+ * const clean = sanitizeUrl(encoded);
+ * // Result: 'https://api.com?v=1&sp=/triggers'
+ */
+export function sanitizeUrl(url: string): string {
+  if (!url) return url;
+
+  let sanitized = url;
+
+  // Step 1: Decode Unicode escapes (\u0026 → &)
+  // Common when URLs are stored in JSON or JavaScript strings
+  sanitized = sanitized.replace(/\\u0026/g, '&');
+
+  // Step 2: Decode HTML entities (&amp; → &, &lt; → <, &gt; → >)
+  // Common when URLs are copied from HTML documents
+  sanitized = sanitized.replace(/&amp;/g, '&');
+  sanitized = sanitized.replace(/&lt;/g, '<');
+  sanitized = sanitized.replace(/&gt;/g, '>');
+  sanitized = sanitized.replace(/&quot;/g, '"');
+
+  // Step 3: Decode URL encoding (%26 → &, %3D → =, etc.)
+  // Common when URLs are copied from browsers
+  // Note: We only decode the query string part to preserve intentional encoding
+  try {
+    const urlObj = new URL(sanitized);
+    const searchParams = new URLSearchParams(urlObj.search);
+
+    // Rebuild query string from decoded parameters
+    const params: string[] = [];
+    searchParams.forEach((value, key) => {
+      params.push(`${decodeURIComponent(key)}=${decodeURIComponent(value)}`);
+    });
+
+    if (params.length > 0) {
+      sanitized = `${urlObj.origin}${urlObj.pathname}?${params.join('&')}${urlObj.hash}`;
+    }
+  } catch (e) {
+    // If URL parsing fails, return the partially sanitized version
+    // This handles cases where the URL is malformed
+  }
+
+  return sanitized;
+}
+
+/**
+ * Validate that a URL is properly formatted for Azure Logic Apps
+ *
+ * Checks for common issues:
+ * - Contains encoded characters that should be decoded
+ * - Has required query parameters (api-version, sp, sv, sig)
+ * - Is a valid HTTPS URL
+ *
+ * @param url - The URL to validate
+ * @returns Object with validation result and any issues found
+ */
+export function validatePowerAutomateUrl(url: string): {
+  valid: boolean;
+  issues: string[];
+  warnings: string[];
+} {
+  const issues: string[] = [];
+  const warnings: string[] = [];
+
+  if (!url) {
+    issues.push('URL is empty');
+    return { valid: false, issues, warnings };
+  }
+
+  // Check for encoded characters that should be decoded
+  if (url.includes('\\u0026')) {
+    warnings.push('URL contains Unicode escapes (\\u0026). These will be auto-decoded.');
+  }
+  if (url.includes('&amp;')) {
+    warnings.push('URL contains HTML entities (&amp;). These will be auto-decoded.');
+  }
+
+  // Try to parse the URL
+  try {
+    const urlObj = new URL(sanitizeUrl(url));
+
+    // Must be HTTPS for Azure Logic Apps
+    if (urlObj.protocol !== 'https:') {
+      issues.push('URL must use HTTPS protocol for Azure Logic Apps');
+    }
+
+    // Check for required Azure Logic Apps query parameters
+    const searchParams = new URLSearchParams(urlObj.search);
+
+    if (!searchParams.has('api-version')) {
+      issues.push('Missing required parameter: api-version');
+    }
+    if (!searchParams.has('sp')) {
+      warnings.push(
+        'Missing "sp" parameter (shared access policy). May be required depending on your Logic App configuration.'
+      );
+    }
+    if (!searchParams.has('sv')) {
+      warnings.push(
+        'Missing "sv" parameter (signature version). May be required depending on your Logic App configuration.'
+      );
+    }
+    if (!searchParams.has('sig')) {
+      warnings.push('Missing "sig" parameter (signature). May be required for authentication.');
+    }
+
+  } catch (e) {
+    issues.push(`Invalid URL format: ${e instanceof Error ? e.message : 'Unknown error'}`);
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    warnings,
+  };
+}
+
+/**
+ * Test if a URL is reachable by making a HEAD request
+ *
+ * @param url - The URL to test
+ * @param timeoutMs - Timeout in milliseconds (default: 10000)
+ * @returns Object with reachability status and any error message
+ */
+export async function testUrlReachability(
+  url: string,
+  timeoutMs: number = 10000
+): Promise<{
+  reachable: boolean;
+  statusCode?: number;
+  error?: string;
+}> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const sanitized = sanitizeUrl(url);
+
+    // Make a HEAD request to avoid downloading large payloads
+    const response = await fetch(sanitized, {
+      method: 'HEAD',
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeout);
+
+    return {
+      reachable: response.ok,
+      statusCode: response.status,
+    };
+  } catch (error) {
+    clearTimeout(timeout);
+
+    if (error instanceof Error && error.name === 'AbortError') {
+      return {
+        reachable: false,
+        error: `Request timed out after ${timeoutMs}ms`,
+      };
+    }
+
+    return {
+      reachable: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    };
+  }
+}
+
+/**
+ * Extract query parameters from a URL
+ *
+ * @param url - The URL to parse
+ * @returns Map of parameter names to values
+ */
+export function extractQueryParams(url: string): Map<string, string> {
+  const params = new Map<string, string>();
+
+  try {
+    const sanitized = sanitizeUrl(url);
+    const urlObj = new URL(sanitized);
+    const searchParams = new URLSearchParams(urlObj.search);
+
+    searchParams.forEach((value, key) => {
+      params.set(key, value);
+    });
+  } catch (e) {
+    // Return empty map if URL is malformed
+  }
+
+  return params;
+}
+
+/**
+ * Check if a URL has any encoding issues that need fixing
+ *
+ * @param url - The URL to check
+ * @returns True if the URL has encoding issues, false otherwise
+ */
+export function hasEncodingIssues(url: string): boolean {
+  if (!url) return false;
+
+  return (
+    url.includes('\\u0026') ||
+    url.includes('&amp;') ||
+    url.includes('&lt;') ||
+    url.includes('&gt;') ||
+    url.includes('&quot;')
+  );
+}
+
+/**
+ * SECURITY: Validate URL scheme for user-controlled hyperlink replacements
+ *
+ * Prevents XSS-like attacks by rejecting dangerous URL schemes that could:
+ * - Execute JavaScript (javascript:)
+ * - Embed data URIs (data:)
+ * - Access local files (file:///)
+ * - Use other non-HTTP protocols
+ *
+ * @param url - The URL to validate
+ * @returns Object with validation result and error message if invalid
+ *
+ * @example
+ * validateUrlScheme('https://example.com') // { valid: true, isHttp: true }
+ * validateUrlScheme('javascript:alert(1)') // { valid: false, error: '...', isHttp: false }
+ */
+export function validateUrlScheme(url: string): {
+  valid: boolean;
+  isHttp: boolean;
+  error?: string;
+} {
+  if (!url || url.trim() === '') {
+    return { valid: true, isHttp: false }; // Allow empty (will be handled elsewhere)
+  }
+
+  try {
+    // Attempt to parse as URL
+    const parsed = new URL(url);
+
+    // Whitelist only HTTP/HTTPS protocols
+    const allowedSchemes = ['http:', 'https:'];
+    const isAllowed = allowedSchemes.includes(parsed.protocol.toLowerCase());
+
+    if (!isAllowed) {
+      return {
+        valid: false,
+        isHttp: false,
+        error: `Dangerous URL scheme detected: "${parsed.protocol}". Only http:// and https:// are allowed for security.`,
+      };
+    }
+
+    return { valid: true, isHttp: true };
+  } catch (error) {
+    // If URL parsing fails, it might be a relative URL or malformed
+    // Check for obvious dangerous patterns even if URL parse fails
+    const lowerUrl = url.toLowerCase().trim();
+
+    if (lowerUrl.startsWith('javascript:')) {
+      return {
+        valid: false,
+        isHttp: false,
+        error: 'JavaScript URLs are not allowed for security reasons.',
+      };
+    }
+
+    if (lowerUrl.startsWith('data:')) {
+      return {
+        valid: false,
+        isHttp: false,
+        error: 'Data URLs are not allowed for security reasons.',
+      };
+    }
+
+    if (lowerUrl.startsWith('file:')) {
+      return {
+        valid: false,
+        isHttp: false,
+        error: 'File URLs are not allowed for security reasons.',
+      };
+    }
+
+    // If it's not a parseable URL and doesn't match dangerous patterns,
+    // it might be a content ID or relative path - allow it
+    return { valid: true, isHttp: false };
+  }
+}

package/src/utils/urlPatterns.ts

@@ -0,0 +1,198 @@
+/**
+ * URL Pattern Utilities for theSource Hyperlink Processing
+ *
+ * SINGLE SOURCE OF TRUTH for Content ID and Document ID extraction
+ * Used across all hyperlink processing services
+ *
+ * This utility centralizes regex patterns that were previously duplicated across:
+ * - HyperlinkService.ts
+ * - WordDocumentProcessor.ts
+ * - HyperlinkManager.ts
+ * - DocXMLaterProcessor.ts
+ * - types/hyperlink.ts
+ */
+
+/**
+ * Regex Patterns for theSource URLs
+ *
+ * Content ID Format: TSRC-ABC-123456 or CMS-XYZ-789012
+ * Document ID Format: docid=<uuid-or-alphanumeric>
+ */
+export const URL_PATTERNS = {
+  /**
+   * Matches theSource Content IDs
+   * Examples: TSRC-ABC-123456, CMS-XYZ-789012
+   * Pattern: (TSRC|CMS)-(alphanumeric)-(6 digits)
+   *
+   * Format Specification:
+   * - Prefix: TSRC or CMS
+   * - Separator: hyphen (-)
+   * - Middle: alphanumeric characters (A-Z, a-z, 0-9)
+   * - Separator: hyphen (-)
+   * - Suffix: exactly 6 digits
+   */
+  CONTENT_ID: /(TSRC|CMS)-([a-zA-Z0-9]+)-(\d{6})/i,
+
+  /**
+   * Matches theSource Document IDs
+   * Examples: docid=abc-123-def, docid=abc123
+   * Pattern: docid=(alphanumeric with dashes)
+   *
+   * Format Specification:
+   * - Prefix: docid= (case-insensitive)
+   * - Value: alphanumeric characters with optional hyphens
+   * - Boundary: stops at non-alphanumeric/dash character or end of string
+   */
+  DOCUMENT_ID: /docid=([a-zA-Z0-9-]+)(?:[^a-zA-Z0-9-]|$)/i,
+
+  /**
+   * Matches theSource domain
+   * Example: thesource.cvshealth.com
+   */
+  THE_SOURCE_DOMAIN: /thesource\.cvshealth\.com/i,
+} as const;
+
+/**
+ * Extract Content ID from a URL
+ *
+ * @param url - URL to extract from
+ * @returns Content ID (e.g., "TSRC-ABC-123456") or null if not found
+ *
+ * @example
+ * extractContentId('https://thesource.com/doc?Content_ID=TSRC-ABC-123456')
+ * // Returns: "TSRC-ABC-123456"
+ *
+ * extractContentId('https://google.com')
+ * // Returns: null
+ */
+export function extractContentId(url: string): string | null {
+  if (!url) return null;
+  const match = url.match(URL_PATTERNS.CONTENT_ID);
+  return match ? match[0] : null; // Return full match (TSRC-ABC-123456)
+}
+
+/**
+ * Extract Content ID from any text string (file path, display text, etc.)
+ *
+ * This is used as a fallback when the URL is not available from getUrl(),
+ * such as with file-type hyperlinks where the URL is stored in the
+ * relationship target but getUrl() returns undefined.
+ *
+ * @param text - Text to search for Content_ID pattern
+ * @returns Content ID (e.g., "TSRC-ABC-123456") or null if not found
+ *
+ * @example
+ * extractContentIdFromText('C:\\Users\\user\\Downloads\\TSRC-PROD-015483')
+ * // Returns: "TSRC-PROD-015483"
+ *
+ * extractContentIdFromText('Document: TSRC-ABC-123456 (Final)')
+ * // Returns: "TSRC-ABC-123456"
+ *
+ * extractContentIdFromText('Reviewing SharePoint Errors (Seniors Only)')
+ * // Returns: null
+ */
+export function extractContentIdFromText(text: string): string | null {
+  if (!text) return null;
+  const match = text.match(URL_PATTERNS.CONTENT_ID);
+  return match ? match[0] : null;
+}
+
+/**
+ * Extract Document ID from a URL
+ *
+ * @param url - URL to extract from
+ * @returns Document ID (UUID/alphanumeric) or null if not found
+ *
+ * @example
+ * extractDocumentId('https://thesource.com/#!/view?docid=abc-123-def')
+ * // Returns: "abc-123-def"
+ *
+ * extractDocumentId('https://thesource.com/#!/view?docid=abc123#content')
+ * // Returns: "abc123"
+ *
+ * extractDocumentId('https://google.com')
+ * // Returns: null
+ */
+export function extractDocumentId(url: string): string | null {
+  if (!url) return null;
+  const match = url.match(URL_PATTERNS.DOCUMENT_ID);
+  return match ? match[1] : null; // Return captured group (the ID itself)
+}
+
+/**
+ * Extract both Lookup IDs (Content ID and Document ID) from a URL
+ *
+ * This is the primary method used by WordDocumentProcessor for API lookups.
+ * It attempts to extract both types of IDs and returns whichever are found.
+ *
+ * @param url - URL to extract from
+ * @returns Object with contentId and/or documentId, or null if neither found
+ *
+ * @example
+ * extractLookupIds('https://thesource.com/doc?Content_ID=TSRC-ABC-123456&docid=abc123')
+ * // Returns: { contentId: "TSRC-ABC-123456", documentId: "abc123" }
+ *
+ * extractLookupIds('https://thesource.com/doc?Content_ID=TSRC-ABC-123456')
+ * // Returns: { contentId: "TSRC-ABC-123456" }
+ *
+ * extractLookupIds('https://google.com')
+ * // Returns: null
+ */
+export function extractLookupIds(url: string): {
+  contentId?: string;
+  documentId?: string;
+} | null {
+  if (!url) return null;
+
+  const lookupIds: { contentId?: string; documentId?: string } = {};
+
+  const contentId = extractContentId(url);
+  if (contentId) {
+    lookupIds.contentId = contentId;
+  }
+
+  const documentId = extractDocumentId(url);
+  if (documentId) {
+    lookupIds.documentId = documentId;
+  }
+
+  return Object.keys(lookupIds).length > 0 ? lookupIds : null;
+}
+
+/**
+ * Check if URL is a theSource URL
+ *
+ * @param url - URL to check
+ * @returns true if theSource URL, false otherwise
+ *
+ * @example
+ * isTheSourceUrl('https://thesource.cvshealth.com/nuxeo/...')
+ * // Returns: true
+ *
+ * isTheSourceUrl('https://google.com')
+ * // Returns: false
+ */
+export function isTheSourceUrl(url: string): boolean {
+  if (!url) return false;
+  return URL_PATTERNS.THE_SOURCE_DOMAIN.test(url);
+}
+
+/**
+ * Check if URL has a Content ID
+ *
+ * @param url - URL to check
+ * @returns true if Content ID found
+ */
+export function hasContentId(url: string): boolean {
+  return extractContentId(url) !== null;
+}
+
+/**
+ * Check if URL has a Document ID
+ *
+ * @param url - URL to check
+ * @returns true if Document ID found
+ */
+export function hasDocumentId(url: string): boolean {
+  return extractDocumentId(url) !== null;
+}