@character-foundry/character-foundry 0.1.9 → 0.4.0-dev.1765937896

package/dist/image-utils.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/image-utils.ts","../../image-utils/src/extraction.ts","../../image-utils/src/ssrf.ts"],"sourcesContent":["export * from '@character-foundry/image-utils';\n","/**\n * Image URL Extraction\n *\n * Extracts image URLs from markdown, HTML, and base64 data URLs in text.\n * Used across Federation, Archive, and Architect for image processing.\n */\n\nexport interface ImageExtractionOptions {\n  /** Include markdown image syntax `![alt](url)` (default: true) */\n  includeMarkdown?: boolean;\n  /** Include HTML img tags `<img src=\"url\">` (default: true) */\n  includeHTML?: boolean;\n  /** Include base64 data URLs `data:image/...;base64,...` (default: true) */\n  includeBase64?: boolean;\n}\n\nexport interface ExtractedImage {\n  /** The extracted URL or data URL */\n  url: string;\n  /** Source format where the image was found */\n  source: 'markdown' | 'html' | 'base64';\n  /** Surrounding context for debugging (optional) */\n  context?: string;\n}\n\n/**\n * Extract all image URLs from text.\n *\n * Supports markdown, HTML, and base64 data URLs.\n * Returns deduplicated results.\n *\n * @param text - Text to extract image URLs from\n * @param options - Extraction options\n * @returns Array of extracted images with source information\n *\n * @example\n * ```typescript\n * const text = 'Check out ![portrait](avatar.png) and <img src=\"banner.jpg\">';\n * const images = extractImageUrls(text);\n * // [\n * //   { url: 'avatar.png', source: 'markdown' },\n * //   { url: 'banner.jpg', source: 'html' }\n * // ]\n * ```\n */\nexport function extractImageUrls(\n  text: string,\n  options: ImageExtractionOptions = {},\n): ExtractedImage[] {\n  const {\n    includeMarkdown = true,\n    includeHTML = true,\n    includeBase64 = true,\n  } = options;\n\n  const results: ExtractedImage[] = [];\n  const seen = new Set<string>();\n\n  // Extract markdown images: ![alt](url) or ![alt](<url>) or ![alt](url =dimensions)\n  // Supports: standard, angle brackets, and SillyTavern dimension syntax\n  if (includeMarkdown) {\n    const markdownPattern = /!\\[([^\\]]*)\\]\\(<?([^>\\s)]+)>?(?:\\s*=[^)]+)?\\)/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = markdownPattern.exec(text)) !== null) {\n      const url = match[2]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'markdown',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract HTML img tags: <img src=\"url\"> (quoted and unquoted)\n  if (includeHTML) {\n    // Quoted src\n    const htmlQuotedPattern = /<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = htmlQuotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // Unquoted src (e.g., <img src=url>)\n    const htmlUnquotedPattern = /<img[^>]+src=([^\\s\"'>]+)[^>]*>/gi;\n    while ((match = htmlUnquotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Skip if it starts with a quote (already handled above)\n      if (url && !url.startsWith('\"') && !url.startsWith(\"'\") && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // CSS url() function: url(url), url(\"url\"), url('url')\n    // Common in background-image, background, content properties\n    const cssUrlPattern = /url\\([\"']?([^)\"']+)[\"']?\\)/gi;\n    while ((match = cssUrlPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Only include http(s) URLs to avoid CSS variables and relative paths\n      if (url && (url.startsWith('http://') || url.startsWith('https://')) && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract plain image URLs (not wrapped in any syntax)\n  if (includeHTML) {\n    // Plain URLs with image extensions (common on image hosts)\n    const plainUrlPattern = /(?<![(\"'])(https?:\\/\\/[^\\s<>\"']+\\.(?:jpg|jpeg|png|gif|webp|svg|avif|bmp))(?![)\"'])/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = plainUrlPattern.exec(text)) !== null) {\n      const url = match[0]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: url,\n        });\n      }\n    }\n  }\n\n  // Extract base64 data URLs: data:image/...;base64,...\n  if (includeBase64) {\n    const dataUrlPattern = /data:image\\/[^;]+;base64,[A-Za-z0-9+/=]+/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = dataUrlPattern.exec(text)) !== null) {\n      const url = match[0];\n      if (!seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'base64',\n        });\n      }\n    }\n  }\n\n  return results;\n}\n\n/**\n * Extract only HTTP/HTTPS URLs (excludes data URLs and relative paths).\n *\n * Convenience wrapper around extractImageUrls that filters for remote URLs.\n *\n * @param text - Text to extract URLs from\n * @returns Array of extracted HTTP/HTTPS image URLs\n */\nexport function extractRemoteImageUrls(text: string): ExtractedImage[] {\n  const all = extractImageUrls(text, { includeBase64: false });\n  return all.filter((img) => /^https?:\\/\\//i.test(img.url));\n}\n\n/**\n * Extract only base64 data URLs.\n *\n * Convenience wrapper around extractImageUrls.\n *\n * @param text - Text to extract data URLs from\n * @returns Array of base64 image data URLs\n */\nexport function extractDataUrls(text: string): ExtractedImage[] {\n  return extractImageUrls(text, {\n    includeMarkdown: false,\n    includeHTML: false,\n    includeBase64: true,\n  });\n}\n\n/**\n * Count images in text without extracting full details.\n *\n * More efficient than extractImageUrls when you only need the count.\n *\n * @param text - Text to count images in\n * @returns Total number of unique image references\n */\nexport function countImages(text: string): number {\n  return extractImageUrls(text).length;\n}\n","/**\n * SSRF (Server-Side Request Forgery) Protection\n *\n * Validates URLs to prevent SSRF attacks.\n * Browser-safe implementation (no Node.js dependencies).\n */\n\nexport interface SSRFPolicy {\n  /** Allow private IP addresses (10.x, 172.16-31.x, 192.168.x) (default: false) */\n  allowPrivateIPs?: boolean;\n  /** Allow localhost/loopback (127.x, ::1) (default: false) */\n  allowLocalhost?: boolean;\n  /** Blocked domain patterns (e.g., ['internal.company.com', '*.local']) */\n  blockedDomains?: string[];\n  /** Allowed domain patterns - if provided, ONLY these are allowed */\n  allowedDomains?: string[];\n  /** Allow data URLs (data:image/...) (default: false) */\n  allowDataUrls?: boolean;\n}\n\nexport interface SafetyCheck {\n  /** Whether the URL is safe according to policy */\n  safe: boolean;\n  /** Reason why URL is unsafe (if safe=false) */\n  reason?: string;\n}\n\n/**\n * Default SSRF policy - blocks private IPs, localhost, and data URLs.\n */\nexport const DEFAULT_SSRF_POLICY: Required<SSRFPolicy> = {\n  allowPrivateIPs: false,\n  allowLocalhost: false,\n  blockedDomains: [],\n  allowedDomains: [],\n  allowDataUrls: false,\n};\n\n/**\n * Check if URL is safe to fetch according to SSRF policy.\n *\n * This is the canonical SSRF protection - all apps should use this\n * before fetching external URLs.\n *\n * @param url - URL to validate\n * @param policy - SSRF policy (uses defaults if not provided)\n * @returns Safety check result with reason if unsafe\n *\n * @example\n * ```typescript\n * const check = isURLSafe('http://10.0.0.1/secret');\n * if (!check.safe) {\n *   console.error('Unsafe URL:', check.reason);\n * }\n * ```\n */\nexport function isURLSafe(\n  url: string,\n  policy: SSRFPolicy = {},\n): SafetyCheck {\n  const config = { ...DEFAULT_SSRF_POLICY, ...policy };\n\n  // Parse URL\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return { safe: false, reason: 'Invalid URL format' };\n  }\n\n  // Check protocol\n  if (parsed.protocol === 'data:') {\n    if (!config.allowDataUrls) {\n      return { safe: false, reason: 'Data URLs not allowed' };\n    }\n    return { safe: true };\n  }\n\n  if (!['http:', 'https:'].includes(parsed.protocol)) {\n    return {\n      safe: false,\n      reason: `Protocol '${parsed.protocol}' not allowed (only http/https)`,\n    };\n  }\n\n  const hostname = parsed.hostname.toLowerCase();\n\n  // Check allowed domains (whitelist)\n  if (config.allowedDomains.length > 0) {\n    const isAllowed = config.allowedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (!isAllowed) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' not in allowed list`,\n      };\n    }\n  }\n\n  // Check blocked domains (blacklist)\n  if (config.blockedDomains.length > 0) {\n    const isBlocked = config.blockedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (isBlocked) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' is blocked`,\n      };\n    }\n  }\n\n  // Check localhost\n  if (isLocalhost(hostname) && !config.allowLocalhost) {\n    return { safe: false, reason: 'Localhost not allowed' };\n  }\n\n  // Check private IPs\n  if (isPrivateIP(hostname) && !config.allowPrivateIPs) {\n    return { safe: false, reason: 'Private IP addresses not allowed' };\n  }\n\n  return { safe: true };\n}\n\n/**\n * Quick check if URL is safe with default policy.\n *\n * Convenience wrapper for common case.\n *\n * @param url - URL to validate\n * @returns true if safe, false otherwise\n */\nexport function isSafeForFetch(url: string): boolean {\n  return isURLSafe(url).safe;\n}\n\n/**\n * Match domain against pattern (supports wildcards).\n *\n * @example\n * ```typescript\n * matchDomainPattern('api.github.com', '*.github.com') // true\n * matchDomainPattern('github.com', '*.github.com') // false\n * matchDomainPattern('github.com', 'github.com') // true\n * ```\n */\nfunction matchDomainPattern(domain: string, pattern: string): boolean {\n  // Exact match\n  if (domain === pattern) return true;\n\n  // Wildcard match - only matches subdomains, not the base domain\n  if (pattern.startsWith('*.')) {\n    const suffix = pattern.slice(2);\n    return domain.endsWith('.' + suffix);\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is localhost/loopback.\n */\nfunction isLocalhost(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 loopback\n  if (lower === 'localhost' || lower === '0.0.0.0' || lower.startsWith('127.')) {\n    return true;\n  }\n\n  // IPv6 loopback\n  if (lower === '::1' || lower === '[::1]') {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is a private IP address.\n *\n * Checks for:\n * - 10.0.0.0/8\n * - 172.16.0.0/12\n * - 192.168.0.0/16\n * - Link-local: 169.254.0.0/16 (includes AWS metadata endpoint)\n * - IPv6 private ranges\n */\nfunction isPrivateIP(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 private ranges\n  const parts = hostname.split('.').map(Number);\n\n  if (\n    parts.length === 4 &&\n    parts.every((p) => p >= 0 && p <= 255 && !isNaN(p))\n  ) {\n    const [octet1, octet2] = parts;\n\n    // 10.0.0.0/8\n    if (octet1 === 10) return true;\n\n    // 172.16.0.0/12\n    if (octet1 === 172 && octet2 !== undefined && octet2 >= 16 && octet2 <= 31)\n      return true;\n\n    // 192.168.0.0/16\n    if (octet1 === 192 && octet2 === 168) return true;\n\n    // 169.254.0.0/16 (link-local) - includes AWS metadata endpoint\n    if (octet1 === 169 && octet2 === 254) return true;\n  }\n\n  // IPv6 private ranges using regex patterns\n  // Strip brackets if present (URL parser adds them: [fc00::1])\n  const cleanedHostname = lower.replace(/^\\[|\\]$/g, '');\n\n  const ipv6Patterns = [\n    /^f[cd][0-9a-f]{2}:/i, // fc00::/7 (includes both fc and fd ranges)\n    /^fe80:/i, // fe80::/10 (link-local)\n  ];\n\n  for (const pattern of ipv6Patterns) {\n    if (pattern.test(cleanedHostname)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Filter array of URLs, keeping only safe ones.\n *\n * @param urls - Array of URLs to filter\n * @param policy - SSRF policy\n * @returns Array of safe URLs\n */\nexport function filterSafeUrls(\n  urls: string[],\n  policy?: SSRFPolicy,\n): string[] {\n  return urls.filter((url) => isURLSafe(url, policy).safe);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC6CO,SAAS,iBACd,MACA,UAAkC,CAAC,GACjB;AAClB,QAAM;IACJ,kBAAkB;IAClB,cAAc;IACd,gBAAgB;EAClB,IAAI;AAEJ,QAAM,UAA4B,CAAC;AACnC,QAAM,OAAO,oBAAI,IAAY;AAI7B,MAAI,iBAAiB;AACnB,UAAM,kBAAkB;AACxB,QAAI;AAEJ,YAAQ,QAAQ,gBAAgB,KAAK,IAAI,OAAO,MAAM;AACpD,YAAM,MAAM,MAAM,CAAC,GAAG,KAAK;AAC3B,UAAI,OAAO,CAAC,KAAK,IAAI,GAAG,GAAG;AACzB,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;UACR,SAAS,MAAM,CAAC;QAClB,CAAC;MACH;IACF;EACF;AAGA,MAAI,aAAa;AAEf,UAAM,oBAAoB;AAC1B,QAAI;AAEJ,YAAQ,QAAQ,kBAAkB,KAAK,IAAI,OAAO,MAAM;AACtD,YAAM,MAAM,MAAM,CAAC,GAAG,KAAK;AAC3B,UAAI,OAAO,CAAC,KAAK,IAAI,GAAG,GAAG;AACzB,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;UACR,SAAS,MAAM,CAAC;QAClB,CAAC;MACH;IACF;AAGA,UAAM,sBAAsB;AAC5B,YAAQ,QAAQ,oBAAoB,KAAK,IAAI,OAAO,MAAM;AACxD,YAAM,MAAM,MAAM,CAAC,GAAG,KAAK;AAE3B,UAAI,OAAO,CAAC,IAAI,WAAW,GAAG,KAAK,CAAC,IAAI,WAAW,GAAG,KAAK,CAAC,KAAK,IAAI,GAAG,GAAG;AACzE,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;UACR,SAAS,MAAM,CAAC;QAClB,CAAC;MACH;IACF;AAIA,UAAM,gBAAgB;AACtB,YAAQ,QAAQ,cAAc,KAAK,IAAI,OAAO,MAAM;AAClD,YAAM,MAAM,MAAM,CAAC,GAAG,KAAK;AAE3B,UAAI,QAAQ,IAAI,WAAW,SAAS,KAAK,IAAI,WAAW,UAAU,MAAM,CAAC,KAAK,IAAI,GAAG,GAAG;AACtF,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;UACR,SAAS,MAAM,CAAC;QAClB,CAAC;MACH;IACF;EACF;AAGA,MAAI,aAAa;AAEf,UAAM,kBAAkB;AACxB,QAAI;AAEJ,YAAQ,QAAQ,gBAAgB,KAAK,IAAI,OAAO,MAAM;AACpD,YAAM,MAAM,MAAM,CAAC,GAAG,KAAK;AAC3B,UAAI,OAAO,CAAC,KAAK,IAAI,GAAG,GAAG;AACzB,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;UACR,SAAS;QACX,CAAC;MACH;IACF;EACF;AAGA,MAAI,eAAe;AACjB,UAAM,iBAAiB;AACvB,QAAI;AAEJ,YAAQ,QAAQ,eAAe,KAAK,IAAI,OAAO,MAAM;AACnD,YAAM,MAAM,MAAM,CAAC;AACnB,UAAI,CAAC,KAAK,IAAI,GAAG,GAAG;AAClB,aAAK,IAAI,GAAG;AACZ,gBAAQ,KAAK;UACX;UACA,QAAQ;QACV,CAAC;MACH;IACF;EACF;AAEA,SAAO;AACT;AAUO,SAAS,uBAAuB,MAAgC;AACrE,QAAM,MAAM,iBAAiB,MAAM,EAAE,eAAe,MAAM,CAAC;AAC3D,SAAO,IAAI,OAAO,CAAC,QAAQ,gBAAgB,KAAK,IAAI,GAAG,CAAC;AAC1D;AAUO,SAAS,gBAAgB,MAAgC;AAC9D,SAAO,iBAAiB,MAAM;IAC5B,iBAAiB;IACjB,aAAa;IACb,eAAe;EACjB,CAAC;AACH;AAUO,SAAS,YAAY,MAAsB;AAChD,SAAO,iBAAiB,IAAI,EAAE;AAChC;AC/KO,IAAM,sBAA4C;EACvD,iBAAiB;EACjB,gBAAgB;EAChB,gBAAgB,CAAC;EACjB,gBAAgB,CAAC;EACjB,eAAe;AACjB;AAoBO,SAAS,UACd,KACA,SAAqB,CAAC,GACT;AACb,QAAM,SAAS,EAAE,GAAG,qBAAqB,GAAG,OAAO;AAGnD,MAAI;AACJ,MAAI;AACF,aAAS,IAAI,IAAI,GAAG;EACtB,QAAQ;AACN,WAAO,EAAE,MAAM,OAAO,QAAQ,qBAAqB;EACrD;AAGA,MAAI,OAAO,aAAa,SAAS;AAC/B,QAAI,CAAC,OAAO,eAAe;AACzB,aAAO,EAAE,MAAM,OAAO,QAAQ,wBAAwB;IACxD;AACA,WAAO,EAAE,MAAM,KAAK;EACtB;AAEA,MAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,SAAS,OAAO,QAAQ,GAAG;AAClD,WAAO;MACL,MAAM;MACN,QAAQ,aAAa,OAAO,QAAQ;IACtC;EACF;AAEA,QAAM,WAAW,OAAO,SAAS,YAAY;AAG7C,MAAI,OAAO,eAAe,SAAS,GAAG;AACpC,UAAM,YAAY,OAAO,eAAe;MAAK,CAAC,YAC5C,mBAAmB,UAAU,OAAO;IACtC;AACA,QAAI,CAAC,WAAW;AACd,aAAO;QACL,MAAM;QACN,QAAQ,WAAW,QAAQ;MAC7B;IACF;EACF;AAGA,MAAI,OAAO,eAAe,SAAS,GAAG;AACpC,UAAM,YAAY,OAAO,eAAe;MAAK,CAAC,YAC5C,mBAAmB,UAAU,OAAO;IACtC;AACA,QAAI,WAAW;AACb,aAAO;QACL,MAAM;QACN,QAAQ,WAAW,QAAQ;MAC7B;IACF;EACF;AAGA,MAAI,YAAY,QAAQ,KAAK,CAAC,OAAO,gBAAgB;AACnD,WAAO,EAAE,MAAM,OAAO,QAAQ,wBAAwB;EACxD;AAGA,MAAI,YAAY,QAAQ,KAAK,CAAC,OAAO,iBAAiB;AACpD,WAAO,EAAE,MAAM,OAAO,QAAQ,mCAAmC;EACnE;AAEA,SAAO,EAAE,MAAM,KAAK;AACtB;AAUO,SAAS,eAAe,KAAsB;AACnD,SAAO,UAAU,GAAG,EAAE;AACxB;AAYA,SAAS,mBAAmB,QAAgB,SAA0B;AAEpE,MAAI,WAAW,QAAS,QAAO;AAG/B,MAAI,QAAQ,WAAW,IAAI,GAAG;AAC5B,UAAM,SAAS,QAAQ,MAAM,CAAC;AAC9B,WAAO,OAAO,SAAS,MAAM,MAAM;EACrC;AAEA,SAAO;AACT;AAKA,SAAS,YAAY,UAA2B;AAC9C,QAAM,QAAQ,SAAS,YAAY;AAGnC,MAAI,UAAU,eAAe,UAAU,aAAa,MAAM,WAAW,MAAM,GAAG;AAC5E,WAAO;EACT;AAGA,MAAI,UAAU,SAAS,UAAU,SAAS;AACxC,WAAO;EACT;AAEA,SAAO;AACT;AAYA,SAAS,YAAY,UAA2B;AAC9C,QAAM,QAAQ,SAAS,YAAY;AAGnC,QAAM,QAAQ,SAAS,MAAM,GAAG,EAAE,IAAI,MAAM;AAE5C,MACE,MAAM,WAAW,KACjB,MAAM,MAAM,CAAC,MAAM,KAAK,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAClD;AACA,UAAM,CAAC,QAAQ,MAAM,IAAI;AAGzB,QAAI,WAAW,GAAI,QAAO;AAG1B,QAAI,WAAW,OAAO,WAAW,UAAa,UAAU,MAAM,UAAU;AACtE,aAAO;AAGT,QAAI,WAAW,OAAO,WAAW,IAAK,QAAO;AAG7C,QAAI,WAAW,OAAO,WAAW,IAAK,QAAO;EAC/C;AAIA,QAAM,kBAAkB,MAAM,QAAQ,YAAY,EAAE;AAEpD,QAAM,eAAe;IACnB;;IACA;;EACF;AAEA,aAAW,WAAW,cAAc;AAClC,QAAI,QAAQ,KAAK,eAAe,GAAG;AACjC,aAAO;IACT;EACF;AAEA,SAAO;AACT;AASO,SAAS,eACd,MACA,QACU;AACV,SAAO,KAAK,OAAO,CAAC,QAAQ,UAAU,KAAK,MAAM,EAAE,IAAI;AACzD;","names":[]}
+{"version":3,"sources":["../src/image-utils.ts","../../image-utils/src/extraction.ts","../../image-utils/src/ssrf.ts"],"sourcesContent":["export * from '@character-foundry/image-utils';\n","/**\n * Image URL Extraction\n *\n * Extracts image URLs from markdown, HTML, and base64 data URLs in text.\n * Used across Federation, Archive, and Architect for image processing.\n */\n\nexport interface ImageExtractionOptions {\n  /** Include markdown image syntax `![alt](url)` (default: true) */\n  includeMarkdown?: boolean;\n  /** Include HTML img tags `<img src=\"url\">` (default: true) */\n  includeHTML?: boolean;\n  /** Include base64 data URLs `data:image/...;base64,...` (default: true) */\n  includeBase64?: boolean;\n}\n\nexport interface ExtractedImage {\n  /** The extracted URL or data URL */\n  url: string;\n  /** Source format where the image was found */\n  source: 'markdown' | 'html' | 'base64';\n  /** Surrounding context for debugging (optional) */\n  context?: string;\n}\n\n/**\n * Extract all image URLs from text.\n *\n * Supports markdown, HTML, and base64 data URLs.\n * Returns deduplicated results.\n *\n * @param text - Text to extract image URLs from\n * @param options - Extraction options\n * @returns Array of extracted images with source information\n *\n * @example\n * ```typescript\n * const text = 'Check out ![portrait](avatar.png) and <img src=\"banner.jpg\">';\n * const images = extractImageUrls(text);\n * // [\n * //   { url: 'avatar.png', source: 'markdown' },\n * //   { url: 'banner.jpg', source: 'html' }\n * // ]\n * ```\n */\nexport function extractImageUrls(\n  text: string,\n  options: ImageExtractionOptions = {},\n): ExtractedImage[] {\n  const {\n    includeMarkdown = true,\n    includeHTML = true,\n    includeBase64 = true,\n  } = options;\n\n  const results: ExtractedImage[] = [];\n  const seen = new Set<string>();\n\n  // Extract markdown images: ![alt](url) or ![alt](<url>) or ![alt](url =dimensions)\n  // Supports: standard, angle brackets, and SillyTavern dimension syntax\n  if (includeMarkdown) {\n    const markdownPattern = /!\\[([^\\]]*)\\]\\(<?([^>\\s)]+)>?(?:\\s*=[^)]+)?\\)/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = markdownPattern.exec(text)) !== null) {\n      const url = match[2]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'markdown',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract HTML img tags: <img src=\"url\"> (quoted and unquoted)\n  if (includeHTML) {\n    // Quoted src\n    const htmlQuotedPattern = /<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = htmlQuotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // Unquoted src (e.g., <img src=url>)\n    const htmlUnquotedPattern = /<img[^>]+src=([^\\s\"'>]+)[^>]*>/gi;\n    while ((match = htmlUnquotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Skip if it starts with a quote (already handled above)\n      if (url && !url.startsWith('\"') && !url.startsWith(\"'\") && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // CSS url() function: url(url), url(\"url\"), url('url')\n    // Common in background-image, background, content properties\n    const cssUrlPattern = /url\\([\"']?([^)\"']+)[\"']?\\)/gi;\n    while ((match = cssUrlPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Only include http(s) URLs to avoid CSS variables and relative paths\n      if (url && (url.startsWith('http://') || url.startsWith('https://')) && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract plain image URLs (not wrapped in any syntax)\n  if (includeHTML) {\n    // Plain URLs with image extensions (common on image hosts)\n    const plainUrlPattern = /(?<![(\"'])(https?:\\/\\/[^\\s<>\"']+\\.(?:jpg|jpeg|png|gif|webp|svg|avif|bmp))(?![)\"'])/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = plainUrlPattern.exec(text)) !== null) {\n      const url = match[0]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: url,\n        });\n      }\n    }\n  }\n\n  // Extract base64 data URLs: data:image/...;base64,...\n  if (includeBase64) {\n    const dataUrlPattern = /data:image\\/[^;]+;base64,[A-Za-z0-9+/=]+/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = dataUrlPattern.exec(text)) !== null) {\n      const url = match[0];\n      if (!seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'base64',\n        });\n      }\n    }\n  }\n\n  return results;\n}\n\n/**\n * Extract only HTTP/HTTPS URLs (excludes data URLs and relative paths).\n *\n * Convenience wrapper around extractImageUrls that filters for remote URLs.\n *\n * @param text - Text to extract URLs from\n * @returns Array of extracted HTTP/HTTPS image URLs\n */\nexport function extractRemoteImageUrls(text: string): ExtractedImage[] {\n  const all = extractImageUrls(text, { includeBase64: false });\n  return all.filter((img) => /^https?:\\/\\//i.test(img.url));\n}\n\n/**\n * Extract only base64 data URLs.\n *\n * Convenience wrapper around extractImageUrls.\n *\n * @param text - Text to extract data URLs from\n * @returns Array of base64 image data URLs\n */\nexport function extractDataUrls(text: string): ExtractedImage[] {\n  return extractImageUrls(text, {\n    includeMarkdown: false,\n    includeHTML: false,\n    includeBase64: true,\n  });\n}\n\n/**\n * Count images in text without extracting full details.\n *\n * More efficient than extractImageUrls when you only need the count.\n *\n * @param text - Text to count images in\n * @returns Total number of unique image references\n */\nexport function countImages(text: string): number {\n  return extractImageUrls(text).length;\n}\n","/**\n * SSRF (Server-Side Request Forgery) Protection\n *\n * Validates URLs to prevent SSRF attacks.\n * Browser-safe implementation (no Node.js dependencies).\n */\n\nexport interface SSRFPolicy {\n  /** Allow private IP addresses (10.x, 172.16-31.x, 192.168.x) (default: false) */\n  allowPrivateIPs?: boolean;\n  /** Allow localhost/loopback (127.x, ::1) (default: false) */\n  allowLocalhost?: boolean;\n  /** Blocked domain patterns (e.g., ['internal.company.com', '*.local']) */\n  blockedDomains?: string[];\n  /** Allowed domain patterns - if provided, ONLY these are allowed */\n  allowedDomains?: string[];\n  /** Allow data URLs (data:image/...) (default: false) */\n  allowDataUrls?: boolean;\n}\n\nexport interface SafetyCheck {\n  /** Whether the URL is safe according to policy */\n  safe: boolean;\n  /** Reason why URL is unsafe (if safe=false) */\n  reason?: string;\n}\n\n/**\n * Default SSRF policy - blocks private IPs, localhost, and data URLs.\n */\nexport const DEFAULT_SSRF_POLICY: Required<SSRFPolicy> = {\n  allowPrivateIPs: false,\n  allowLocalhost: false,\n  blockedDomains: [],\n  allowedDomains: [],\n  allowDataUrls: false,\n};\n\n/**\n * Check if URL is safe to fetch according to SSRF policy.\n *\n * This is the canonical SSRF protection - all apps should use this\n * before fetching external URLs.\n *\n * **Limitations (browser-side validation only):**\n * - Cannot detect domains that resolve to private IPs (e.g., `attacker.com` -> `127.0.0.1`)\n * - Cannot prevent DNS rebinding attacks (domain resolves differently on subsequent requests)\n * - Cannot validate redirect destinations (server may redirect to internal URLs)\n * - Does not perform actual DNS resolution - only validates URL syntax and hostname patterns\n *\n * For server-side applications requiring stronger SSRF protection, perform DNS resolution\n * and validate the resolved IP address before making the request, and validate redirect\n * destinations or disable redirects entirely.\n *\n * @param url - URL to validate\n * @param policy - SSRF policy (uses defaults if not provided)\n * @returns Safety check result with reason if unsafe\n *\n * @see https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html\n *\n * @example\n * ```typescript\n * const check = isURLSafe('http://10.0.0.1/secret');\n * if (!check.safe) {\n *   console.error('Unsafe URL:', check.reason);\n * }\n * ```\n */\nexport function isURLSafe(\n  url: string,\n  policy: SSRFPolicy = {},\n): SafetyCheck {\n  const config = { ...DEFAULT_SSRF_POLICY, ...policy };\n\n  // Parse URL\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return { safe: false, reason: 'Invalid URL format' };\n  }\n\n  // Check protocol\n  if (parsed.protocol === 'data:') {\n    if (!config.allowDataUrls) {\n      return { safe: false, reason: 'Data URLs not allowed' };\n    }\n    return { safe: true };\n  }\n\n  if (!['http:', 'https:'].includes(parsed.protocol)) {\n    return {\n      safe: false,\n      reason: `Protocol '${parsed.protocol}' not allowed (only http/https)`,\n    };\n  }\n\n  const hostname = parsed.hostname.toLowerCase();\n\n  // Check allowed domains (whitelist)\n  if (config.allowedDomains.length > 0) {\n    const isAllowed = config.allowedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (!isAllowed) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' not in allowed list`,\n      };\n    }\n  }\n\n  // Check blocked domains (blacklist)\n  if (config.blockedDomains.length > 0) {\n    const isBlocked = config.blockedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (isBlocked) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' is blocked`,\n      };\n    }\n  }\n\n  // Check localhost\n  if (isLocalhost(hostname) && !config.allowLocalhost) {\n    return { safe: false, reason: 'Localhost not allowed' };\n  }\n\n  // Check private IPs\n  if (isPrivateIP(hostname) && !config.allowPrivateIPs) {\n    return { safe: false, reason: 'Private IP addresses not allowed' };\n  }\n\n  return { safe: true };\n}\n\n/**\n * Quick check if URL is safe with default policy.\n *\n * Convenience wrapper for common case.\n *\n * @param url - URL to validate\n * @returns true if safe, false otherwise\n */\nexport function isSafeForFetch(url: string): boolean {\n  return isURLSafe(url).safe;\n}\n\n/**\n * Match domain against pattern (supports wildcards).\n *\n * @example\n * ```typescript\n * matchDomainPattern('api.github.com', '*.github.com') // true\n * matchDomainPattern('github.com', '*.github.com') // false\n * matchDomainPattern('github.com', 'github.com') // true\n * ```\n */\nfunction matchDomainPattern(domain: string, pattern: string): boolean {\n  // Exact match\n  if (domain === pattern) return true;\n\n  // Wildcard match - only matches subdomains, not the base domain\n  if (pattern.startsWith('*.')) {\n    const suffix = pattern.slice(2);\n    return domain.endsWith('.' + suffix);\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is localhost/loopback.\n */\nfunction isLocalhost(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 loopback\n  if (lower === 'localhost' || lower === '0.0.0.0' || lower.startsWith('127.')) {\n    return true;\n  }\n\n  // IPv6 loopback\n  if (lower === '::1' || lower === '[::1]') {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is a private IP address.\n *\n * Checks for:\n * - 10.0.0.0/8\n * - 172.16.0.0/12\n * - 192.168.0.0/16\n * - Link-local: 169.254.0.0/16 (includes AWS metadata endpoint)\n * - IPv6 private ranges\n */\nfunction isPrivateIP(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 private ranges\n  const parts = hostname.split('.').map(Number);\n\n  if (\n    parts.length === 4 &&\n    parts.every((p) => p >= 0 && p <= 255 && !isNaN(p))\n  ) {\n    const [octet1, octet2] = parts;\n\n    // 10.0.0.0/8\n    if (octet1 === 10) return true;\n\n    // 172.16.0.0/12\n    if (octet1 === 172 && octet2 !== undefined && octet2 >= 16 && octet2 <= 31)\n      return true;\n\n    // 192.168.0.0/16\n    if (octet1 === 192 && octet2 === 168) return true;\n\n    // 169.254.0.0/16 (link-local) - includes AWS metadata endpoint\n    if (octet1 === 169 && octet2 === 254) return true;\n  }\n\n  // IPv6 private ranges using regex patterns\n  // Strip brackets if present (URL parser adds them: [fc00::1])\n  const cleanedHostname = lower.replace(/^\\[|\\]$/g, '');\n\n  const ipv6Patterns = [\n    /^f[cd][0-9a-f]{2}:/i, // fc00::/7 (includes both fc and fd ranges)\n    /^fe80:/i, // fe80::/10 (link-local)\n  ];\n\n  for (const pattern of ipv6Patterns) {\n    if (pattern.test(cleanedHostname)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Filter array of URLs, keeping only safe ones.\n *\n * @param urls - Array of URLs to filter\n * @param policy - SSRF policy\n * @returns Array of safe URLs\n */\nexport function filterSafeUrls(\n  urls: string[],\n  policy?: SSRFPolicy,\n): string[] {\n  return urls.filter((url) => isURLSafe(url, policy).safe);\n}\n"],"mappings":"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","names":[]}

package/dist/image-utils.d.cts

@@ -102,10 +102,22 @@ export declare const DEFAULT_SSRF_POLICY: Required<SSRFPolicy>;
  * This is the canonical SSRF protection - all apps should use this
  * before fetching external URLs.
  *
+ * **Limitations (browser-side validation only):**
+ * - Cannot detect domains that resolve to private IPs (e.g., `attacker.com` -> `127.0.0.1`)
+ * - Cannot prevent DNS rebinding attacks (domain resolves differently on subsequent requests)
+ * - Cannot validate redirect destinations (server may redirect to internal URLs)
+ * - Does not perform actual DNS resolution - only validates URL syntax and hostname patterns
+ *
+ * For server-side applications requiring stronger SSRF protection, perform DNS resolution
+ * and validate the resolved IP address before making the request, and validate redirect
+ * destinations or disable redirects entirely.
+ *
  * @param url - URL to validate
  * @param policy - SSRF policy (uses defaults if not provided)
  * @returns Safety check result with reason if unsafe
  *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
+ *
  * @example
  * ```typescript
  * const check = isURLSafe('http://10.0.0.1/secret');

package/dist/image-utils.d.ts

@@ -102,10 +102,22 @@ export declare const DEFAULT_SSRF_POLICY: Required<SSRFPolicy>;
  * This is the canonical SSRF protection - all apps should use this
  * before fetching external URLs.
  *
+ * **Limitations (browser-side validation only):**
+ * - Cannot detect domains that resolve to private IPs (e.g., `attacker.com` -> `127.0.0.1`)
+ * - Cannot prevent DNS rebinding attacks (domain resolves differently on subsequent requests)
+ * - Cannot validate redirect destinations (server may redirect to internal URLs)
+ * - Does not perform actual DNS resolution - only validates URL syntax and hostname patterns
+ *
+ * For server-side applications requiring stronger SSRF protection, perform DNS resolution
+ * and validate the resolved IP address before making the request, and validate redirect
+ * destinations or disable redirects entirely.
+ *
  * @param url - URL to validate
  * @param policy - SSRF policy (uses defaults if not provided)
  * @returns Safety check result with reason if unsafe
  *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
+ *
  * @example
  * ```typescript
  * const check = isURLSafe('http://10.0.0.1/secret');

package/dist/image-utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../image-utils/src/extraction.ts","../../image-utils/src/ssrf.ts"],"sourcesContent":["/**\n * Image URL Extraction\n *\n * Extracts image URLs from markdown, HTML, and base64 data URLs in text.\n * Used across Federation, Archive, and Architect for image processing.\n */\n\nexport interface ImageExtractionOptions {\n  /** Include markdown image syntax `![alt](url)` (default: true) */\n  includeMarkdown?: boolean;\n  /** Include HTML img tags `<img src=\"url\">` (default: true) */\n  includeHTML?: boolean;\n  /** Include base64 data URLs `data:image/...;base64,...` (default: true) */\n  includeBase64?: boolean;\n}\n\nexport interface ExtractedImage {\n  /** The extracted URL or data URL */\n  url: string;\n  /** Source format where the image was found */\n  source: 'markdown' | 'html' | 'base64';\n  /** Surrounding context for debugging (optional) */\n  context?: string;\n}\n\n/**\n * Extract all image URLs from text.\n *\n * Supports markdown, HTML, and base64 data URLs.\n * Returns deduplicated results.\n *\n * @param text - Text to extract image URLs from\n * @param options - Extraction options\n * @returns Array of extracted images with source information\n *\n * @example\n * ```typescript\n * const text = 'Check out ![portrait](avatar.png) and <img src=\"banner.jpg\">';\n * const images = extractImageUrls(text);\n * // [\n * //   { url: 'avatar.png', source: 'markdown' },\n * //   { url: 'banner.jpg', source: 'html' }\n * // ]\n * ```\n */\nexport function extractImageUrls(\n  text: string,\n  options: ImageExtractionOptions = {},\n): ExtractedImage[] {\n  const {\n    includeMarkdown = true,\n    includeHTML = true,\n    includeBase64 = true,\n  } = options;\n\n  const results: ExtractedImage[] = [];\n  const seen = new Set<string>();\n\n  // Extract markdown images: ![alt](url) or ![alt](<url>) or ![alt](url =dimensions)\n  // Supports: standard, angle brackets, and SillyTavern dimension syntax\n  if (includeMarkdown) {\n    const markdownPattern = /!\\[([^\\]]*)\\]\\(<?([^>\\s)]+)>?(?:\\s*=[^)]+)?\\)/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = markdownPattern.exec(text)) !== null) {\n      const url = match[2]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'markdown',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract HTML img tags: <img src=\"url\"> (quoted and unquoted)\n  if (includeHTML) {\n    // Quoted src\n    const htmlQuotedPattern = /<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = htmlQuotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // Unquoted src (e.g., <img src=url>)\n    const htmlUnquotedPattern = /<img[^>]+src=([^\\s\"'>]+)[^>]*>/gi;\n    while ((match = htmlUnquotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Skip if it starts with a quote (already handled above)\n      if (url && !url.startsWith('\"') && !url.startsWith(\"'\") && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // CSS url() function: url(url), url(\"url\"), url('url')\n    // Common in background-image, background, content properties\n    const cssUrlPattern = /url\\([\"']?([^)\"']+)[\"']?\\)/gi;\n    while ((match = cssUrlPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Only include http(s) URLs to avoid CSS variables and relative paths\n      if (url && (url.startsWith('http://') || url.startsWith('https://')) && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract plain image URLs (not wrapped in any syntax)\n  if (includeHTML) {\n    // Plain URLs with image extensions (common on image hosts)\n    const plainUrlPattern = /(?<![(\"'])(https?:\\/\\/[^\\s<>\"']+\\.(?:jpg|jpeg|png|gif|webp|svg|avif|bmp))(?![)\"'])/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = plainUrlPattern.exec(text)) !== null) {\n      const url = match[0]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: url,\n        });\n      }\n    }\n  }\n\n  // Extract base64 data URLs: data:image/...;base64,...\n  if (includeBase64) {\n    const dataUrlPattern = /data:image\\/[^;]+;base64,[A-Za-z0-9+/=]+/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = dataUrlPattern.exec(text)) !== null) {\n      const url = match[0];\n      if (!seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'base64',\n        });\n      }\n    }\n  }\n\n  return results;\n}\n\n/**\n * Extract only HTTP/HTTPS URLs (excludes data URLs and relative paths).\n *\n * Convenience wrapper around extractImageUrls that filters for remote URLs.\n *\n * @param text - Text to extract URLs from\n * @returns Array of extracted HTTP/HTTPS image URLs\n */\nexport function extractRemoteImageUrls(text: string): ExtractedImage[] {\n  const all = extractImageUrls(text, { includeBase64: false });\n  return all.filter((img) => /^https?:\\/\\//i.test(img.url));\n}\n\n/**\n * Extract only base64 data URLs.\n *\n * Convenience wrapper around extractImageUrls.\n *\n * @param text - Text to extract data URLs from\n * @returns Array of base64 image data URLs\n */\nexport function extractDataUrls(text: string): ExtractedImage[] {\n  return extractImageUrls(text, {\n    includeMarkdown: false,\n    includeHTML: false,\n    includeBase64: true,\n  });\n}\n\n/**\n * Count images in text without extracting full details.\n *\n * More efficient than extractImageUrls when you only need the count.\n *\n * @param text - Text to count images in\n * @returns Total number of unique image references\n */\nexport function countImages(text: string): number {\n  return extractImageUrls(text).length;\n}\n","/**\n * SSRF (Server-Side Request Forgery) Protection\n *\n * Validates URLs to prevent SSRF attacks.\n * Browser-safe implementation (no Node.js dependencies).\n */\n\nexport interface SSRFPolicy {\n  /** Allow private IP addresses (10.x, 172.16-31.x, 192.168.x) (default: false) */\n  allowPrivateIPs?: boolean;\n  /** Allow localhost/loopback (127.x, ::1) (default: false) */\n  allowLocalhost?: boolean;\n  /** Blocked domain patterns (e.g., ['internal.company.com', '*.local']) */\n  blockedDomains?: string[];\n  /** Allowed domain patterns - if provided, ONLY these are allowed */\n  allowedDomains?: string[];\n  /** Allow data URLs (data:image/...) (default: false) */\n  allowDataUrls?: boolean;\n}\n\nexport interface SafetyCheck {\n  /** Whether the URL is safe according to policy */\n  safe: boolean;\n  /** Reason why URL is unsafe (if safe=false) */\n  reason?: string;\n}\n\n/**\n * Default SSRF policy - blocks private IPs, localhost, and data URLs.\n */\nexport const DEFAULT_SSRF_POLICY: Required<SSRFPolicy> = {\n  allowPrivateIPs: false,\n  allowLocalhost: false,\n  blockedDomains: [],\n  allowedDomains: [],\n  allowDataUrls: false,\n};\n\n/**\n * Check if URL is safe to fetch according to SSRF policy.\n *\n * This is the canonical SSRF protection - all apps should use this\n * before fetching external URLs.\n *\n * @param url - URL to validate\n * @param policy - SSRF policy (uses defaults if not provided)\n * @returns Safety check result with reason if unsafe\n *\n * @example\n * ```typescript\n * const check = isURLSafe('http://10.0.0.1/secret');\n * if (!check.safe) {\n *   console.error('Unsafe URL:', check.reason);\n * }\n * ```\n */\nexport function isURLSafe(\n  url: string,\n  policy: SSRFPolicy = {},\n): SafetyCheck {\n  const config = { ...DEFAULT_SSRF_POLICY, ...policy };\n\n  // Parse URL\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return { safe: false, reason: 'Invalid URL format' };\n  }\n\n  // Check protocol\n  if (parsed.protocol === 'data:') {\n    if (!config.allowDataUrls) {\n      return { safe: false, reason: 'Data URLs not allowed' };\n    }\n    return { safe: true };\n  }\n\n  if (!['http:', 'https:'].includes(parsed.protocol)) {\n    return {\n      safe: false,\n      reason: `Protocol '${parsed.protocol}' not allowed (only http/https)`,\n    };\n  }\n\n  const hostname = parsed.hostname.toLowerCase();\n\n  // Check allowed domains (whitelist)\n  if (config.allowedDomains.length > 0) {\n    const isAllowed = config.allowedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (!isAllowed) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' not in allowed list`,\n      };\n    }\n  }\n\n  // Check blocked domains (blacklist)\n  if (config.blockedDomains.length > 0) {\n    const isBlocked = config.blockedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (isBlocked) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' is blocked`,\n      };\n    }\n  }\n\n  // Check localhost\n  if (isLocalhost(hostname) && !config.allowLocalhost) {\n    return { safe: false, reason: 'Localhost not allowed' };\n  }\n\n  // Check private IPs\n  if (isPrivateIP(hostname) && !config.allowPrivateIPs) {\n    return { safe: false, reason: 'Private IP addresses not allowed' };\n  }\n\n  return { safe: true };\n}\n\n/**\n * Quick check if URL is safe with default policy.\n *\n * Convenience wrapper for common case.\n *\n * @param url - URL to validate\n * @returns true if safe, false otherwise\n */\nexport function isSafeForFetch(url: string): boolean {\n  return isURLSafe(url).safe;\n}\n\n/**\n * Match domain against pattern (supports wildcards).\n *\n * @example\n * ```typescript\n * matchDomainPattern('api.github.com', '*.github.com') // true\n * matchDomainPattern('github.com', '*.github.com') // false\n * matchDomainPattern('github.com', 'github.com') // true\n * ```\n */\nfunction matchDomainPattern(domain: string, pattern: string): boolean {\n  // Exact match\n  if (domain === pattern) return true;\n\n  // Wildcard match - only matches subdomains, not the base domain\n  if (pattern.startsWith('*.')) {\n    const suffix = pattern.slice(2);\n    return domain.endsWith('.' + suffix);\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is localhost/loopback.\n */\nfunction isLocalhost(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 loopback\n  if (lower === 'localhost' || lower === '0.0.0.0' || lower.startsWith('127.')) {\n    return true;\n  }\n\n  // IPv6 loopback\n  if (lower === '::1' || lower === '[::1]') {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is a private IP address.\n *\n * Checks for:\n * - 10.0.0.0/8\n * - 172.16.0.0/12\n * - 192.168.0.0/16\n * - Link-local: 169.254.0.0/16 (includes AWS metadata endpoint)\n * - IPv6 private ranges\n */\nfunction isPrivateIP(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 private ranges\n  const parts = hostname.split('.').map(Number);\n\n  if (\n    parts.length === 4 &&\n    parts.every((p) => p >= 0 && p <= 255 && !isNaN(p))\n  ) {\n    const [octet1, octet2] = parts;\n\n    // 10.0.0.0/8\n    if (octet1 === 10) return true;\n\n    // 172.16.0.0/12\n    if (octet1 === 172 && octet2 !== undefined && octet2 >= 16 && octet2 <= 31)\n      return true;\n\n    // 192.168.0.0/16\n    if (octet1 === 192 && octet2 === 168) return true;\n\n    // 169.254.0.0/16 (link-local) - includes AWS metadata endpoint\n    if (octet1 === 169 && octet2 === 254) return true;\n  }\n\n  // IPv6 private ranges using regex patterns\n  // Strip brackets if present (URL parser adds them: [fc00::1])\n  const cleanedHostname = lower.replace(/^\\[|\\]$/g, '');\n\n  const ipv6Patterns = [\n    /^f[cd][0-9a-f]{2}:/i, // fc00::/7 (includes both fc and fd ranges)\n    /^fe80:/i, // fe80::/10 (link-local)\n  ];\n\n  for (const pattern of ipv6Patterns) {\n    if (pattern.test(cleanedHostname)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Filter array of URLs, keeping only safe ones.\n *\n * @param urls - Array of URLs to filter\n * @param policy - SSRF policy\n * @returns Array of safe URLs\n */\nexport function filterSafeUrls(\n  urls: string[],\n  policy?: SSRFPolicy,\n): string[] {\n  return urls.filter((url) => isURLSafe(url, policy).safe);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../image-utils/src/extraction.ts","../../image-utils/src/ssrf.ts"],"sourcesContent":["/**\n * Image URL Extraction\n *\n * Extracts image URLs from markdown, HTML, and base64 data URLs in text.\n * Used across Federation, Archive, and Architect for image processing.\n */\n\nexport interface ImageExtractionOptions {\n  /** Include markdown image syntax `![alt](url)` (default: true) */\n  includeMarkdown?: boolean;\n  /** Include HTML img tags `<img src=\"url\">` (default: true) */\n  includeHTML?: boolean;\n  /** Include base64 data URLs `data:image/...;base64,...` (default: true) */\n  includeBase64?: boolean;\n}\n\nexport interface ExtractedImage {\n  /** The extracted URL or data URL */\n  url: string;\n  /** Source format where the image was found */\n  source: 'markdown' | 'html' | 'base64';\n  /** Surrounding context for debugging (optional) */\n  context?: string;\n}\n\n/**\n * Extract all image URLs from text.\n *\n * Supports markdown, HTML, and base64 data URLs.\n * Returns deduplicated results.\n *\n * @param text - Text to extract image URLs from\n * @param options - Extraction options\n * @returns Array of extracted images with source information\n *\n * @example\n * ```typescript\n * const text = 'Check out ![portrait](avatar.png) and <img src=\"banner.jpg\">';\n * const images = extractImageUrls(text);\n * // [\n * //   { url: 'avatar.png', source: 'markdown' },\n * //   { url: 'banner.jpg', source: 'html' }\n * // ]\n * ```\n */\nexport function extractImageUrls(\n  text: string,\n  options: ImageExtractionOptions = {},\n): ExtractedImage[] {\n  const {\n    includeMarkdown = true,\n    includeHTML = true,\n    includeBase64 = true,\n  } = options;\n\n  const results: ExtractedImage[] = [];\n  const seen = new Set<string>();\n\n  // Extract markdown images: ![alt](url) or ![alt](<url>) or ![alt](url =dimensions)\n  // Supports: standard, angle brackets, and SillyTavern dimension syntax\n  if (includeMarkdown) {\n    const markdownPattern = /!\\[([^\\]]*)\\]\\(<?([^>\\s)]+)>?(?:\\s*=[^)]+)?\\)/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = markdownPattern.exec(text)) !== null) {\n      const url = match[2]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'markdown',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract HTML img tags: <img src=\"url\"> (quoted and unquoted)\n  if (includeHTML) {\n    // Quoted src\n    const htmlQuotedPattern = /<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = htmlQuotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // Unquoted src (e.g., <img src=url>)\n    const htmlUnquotedPattern = /<img[^>]+src=([^\\s\"'>]+)[^>]*>/gi;\n    while ((match = htmlUnquotedPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Skip if it starts with a quote (already handled above)\n      if (url && !url.startsWith('\"') && !url.startsWith(\"'\") && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n\n    // CSS url() function: url(url), url(\"url\"), url('url')\n    // Common in background-image, background, content properties\n    const cssUrlPattern = /url\\([\"']?([^)\"']+)[\"']?\\)/gi;\n    while ((match = cssUrlPattern.exec(text)) !== null) {\n      const url = match[1]?.trim();\n      // Only include http(s) URLs to avoid CSS variables and relative paths\n      if (url && (url.startsWith('http://') || url.startsWith('https://')) && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: match[0],\n        });\n      }\n    }\n  }\n\n  // Extract plain image URLs (not wrapped in any syntax)\n  if (includeHTML) {\n    // Plain URLs with image extensions (common on image hosts)\n    const plainUrlPattern = /(?<![(\"'])(https?:\\/\\/[^\\s<>\"']+\\.(?:jpg|jpeg|png|gif|webp|svg|avif|bmp))(?![)\"'])/gi;\n    let match: RegExpExecArray | null;\n\n    while ((match = plainUrlPattern.exec(text)) !== null) {\n      const url = match[0]?.trim();\n      if (url && !seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'html',\n          context: url,\n        });\n      }\n    }\n  }\n\n  // Extract base64 data URLs: data:image/...;base64,...\n  if (includeBase64) {\n    const dataUrlPattern = /data:image\\/[^;]+;base64,[A-Za-z0-9+/=]+/g;\n    let match: RegExpExecArray | null;\n\n    while ((match = dataUrlPattern.exec(text)) !== null) {\n      const url = match[0];\n      if (!seen.has(url)) {\n        seen.add(url);\n        results.push({\n          url,\n          source: 'base64',\n        });\n      }\n    }\n  }\n\n  return results;\n}\n\n/**\n * Extract only HTTP/HTTPS URLs (excludes data URLs and relative paths).\n *\n * Convenience wrapper around extractImageUrls that filters for remote URLs.\n *\n * @param text - Text to extract URLs from\n * @returns Array of extracted HTTP/HTTPS image URLs\n */\nexport function extractRemoteImageUrls(text: string): ExtractedImage[] {\n  const all = extractImageUrls(text, { includeBase64: false });\n  return all.filter((img) => /^https?:\\/\\//i.test(img.url));\n}\n\n/**\n * Extract only base64 data URLs.\n *\n * Convenience wrapper around extractImageUrls.\n *\n * @param text - Text to extract data URLs from\n * @returns Array of base64 image data URLs\n */\nexport function extractDataUrls(text: string): ExtractedImage[] {\n  return extractImageUrls(text, {\n    includeMarkdown: false,\n    includeHTML: false,\n    includeBase64: true,\n  });\n}\n\n/**\n * Count images in text without extracting full details.\n *\n * More efficient than extractImageUrls when you only need the count.\n *\n * @param text - Text to count images in\n * @returns Total number of unique image references\n */\nexport function countImages(text: string): number {\n  return extractImageUrls(text).length;\n}\n","/**\n * SSRF (Server-Side Request Forgery) Protection\n *\n * Validates URLs to prevent SSRF attacks.\n * Browser-safe implementation (no Node.js dependencies).\n */\n\nexport interface SSRFPolicy {\n  /** Allow private IP addresses (10.x, 172.16-31.x, 192.168.x) (default: false) */\n  allowPrivateIPs?: boolean;\n  /** Allow localhost/loopback (127.x, ::1) (default: false) */\n  allowLocalhost?: boolean;\n  /** Blocked domain patterns (e.g., ['internal.company.com', '*.local']) */\n  blockedDomains?: string[];\n  /** Allowed domain patterns - if provided, ONLY these are allowed */\n  allowedDomains?: string[];\n  /** Allow data URLs (data:image/...) (default: false) */\n  allowDataUrls?: boolean;\n}\n\nexport interface SafetyCheck {\n  /** Whether the URL is safe according to policy */\n  safe: boolean;\n  /** Reason why URL is unsafe (if safe=false) */\n  reason?: string;\n}\n\n/**\n * Default SSRF policy - blocks private IPs, localhost, and data URLs.\n */\nexport const DEFAULT_SSRF_POLICY: Required<SSRFPolicy> = {\n  allowPrivateIPs: false,\n  allowLocalhost: false,\n  blockedDomains: [],\n  allowedDomains: [],\n  allowDataUrls: false,\n};\n\n/**\n * Check if URL is safe to fetch according to SSRF policy.\n *\n * This is the canonical SSRF protection - all apps should use this\n * before fetching external URLs.\n *\n * **Limitations (browser-side validation only):**\n * - Cannot detect domains that resolve to private IPs (e.g., `attacker.com` -> `127.0.0.1`)\n * - Cannot prevent DNS rebinding attacks (domain resolves differently on subsequent requests)\n * - Cannot validate redirect destinations (server may redirect to internal URLs)\n * - Does not perform actual DNS resolution - only validates URL syntax and hostname patterns\n *\n * For server-side applications requiring stronger SSRF protection, perform DNS resolution\n * and validate the resolved IP address before making the request, and validate redirect\n * destinations or disable redirects entirely.\n *\n * @param url - URL to validate\n * @param policy - SSRF policy (uses defaults if not provided)\n * @returns Safety check result with reason if unsafe\n *\n * @see https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html\n *\n * @example\n * ```typescript\n * const check = isURLSafe('http://10.0.0.1/secret');\n * if (!check.safe) {\n *   console.error('Unsafe URL:', check.reason);\n * }\n * ```\n */\nexport function isURLSafe(\n  url: string,\n  policy: SSRFPolicy = {},\n): SafetyCheck {\n  const config = { ...DEFAULT_SSRF_POLICY, ...policy };\n\n  // Parse URL\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return { safe: false, reason: 'Invalid URL format' };\n  }\n\n  // Check protocol\n  if (parsed.protocol === 'data:') {\n    if (!config.allowDataUrls) {\n      return { safe: false, reason: 'Data URLs not allowed' };\n    }\n    return { safe: true };\n  }\n\n  if (!['http:', 'https:'].includes(parsed.protocol)) {\n    return {\n      safe: false,\n      reason: `Protocol '${parsed.protocol}' not allowed (only http/https)`,\n    };\n  }\n\n  const hostname = parsed.hostname.toLowerCase();\n\n  // Check allowed domains (whitelist)\n  if (config.allowedDomains.length > 0) {\n    const isAllowed = config.allowedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (!isAllowed) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' not in allowed list`,\n      };\n    }\n  }\n\n  // Check blocked domains (blacklist)\n  if (config.blockedDomains.length > 0) {\n    const isBlocked = config.blockedDomains.some((pattern) =>\n      matchDomainPattern(hostname, pattern),\n    );\n    if (isBlocked) {\n      return {\n        safe: false,\n        reason: `Domain '${hostname}' is blocked`,\n      };\n    }\n  }\n\n  // Check localhost\n  if (isLocalhost(hostname) && !config.allowLocalhost) {\n    return { safe: false, reason: 'Localhost not allowed' };\n  }\n\n  // Check private IPs\n  if (isPrivateIP(hostname) && !config.allowPrivateIPs) {\n    return { safe: false, reason: 'Private IP addresses not allowed' };\n  }\n\n  return { safe: true };\n}\n\n/**\n * Quick check if URL is safe with default policy.\n *\n * Convenience wrapper for common case.\n *\n * @param url - URL to validate\n * @returns true if safe, false otherwise\n */\nexport function isSafeForFetch(url: string): boolean {\n  return isURLSafe(url).safe;\n}\n\n/**\n * Match domain against pattern (supports wildcards).\n *\n * @example\n * ```typescript\n * matchDomainPattern('api.github.com', '*.github.com') // true\n * matchDomainPattern('github.com', '*.github.com') // false\n * matchDomainPattern('github.com', 'github.com') // true\n * ```\n */\nfunction matchDomainPattern(domain: string, pattern: string): boolean {\n  // Exact match\n  if (domain === pattern) return true;\n\n  // Wildcard match - only matches subdomains, not the base domain\n  if (pattern.startsWith('*.')) {\n    const suffix = pattern.slice(2);\n    return domain.endsWith('.' + suffix);\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is localhost/loopback.\n */\nfunction isLocalhost(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 loopback\n  if (lower === 'localhost' || lower === '0.0.0.0' || lower.startsWith('127.')) {\n    return true;\n  }\n\n  // IPv6 loopback\n  if (lower === '::1' || lower === '[::1]') {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if hostname is a private IP address.\n *\n * Checks for:\n * - 10.0.0.0/8\n * - 172.16.0.0/12\n * - 192.168.0.0/16\n * - Link-local: 169.254.0.0/16 (includes AWS metadata endpoint)\n * - IPv6 private ranges\n */\nfunction isPrivateIP(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // IPv4 private ranges\n  const parts = hostname.split('.').map(Number);\n\n  if (\n    parts.length === 4 &&\n    parts.every((p) => p >= 0 && p <= 255 && !isNaN(p))\n  ) {\n    const [octet1, octet2] = parts;\n\n    // 10.0.0.0/8\n    if (octet1 === 10) return true;\n\n    // 172.16.0.0/12\n    if (octet1 === 172 && octet2 !== undefined && octet2 >= 16 && octet2 <= 31)\n      return true;\n\n    // 192.168.0.0/16\n    if (octet1 === 192 && octet2 === 168) return true;\n\n    // 169.254.0.0/16 (link-local) - includes AWS metadata endpoint\n    if (octet1 === 169 && octet2 === 254) return true;\n  }\n\n  // IPv6 private ranges using regex patterns\n  // Strip brackets if present (URL parser adds them: [fc00::1])\n  const cleanedHostname = lower.replace(/^\\[|\\]$/g, '');\n\n  const ipv6Patterns = [\n    /^f[cd][0-9a-f]{2}:/i, // fc00::/7 (includes both fc and fd ranges)\n    /^fe80:/i, // fe80::/10 (link-local)\n  ];\n\n  for (const pattern of ipv6Patterns) {\n    if (pattern.test(cleanedHostname)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Filter array of URLs, keeping only safe ones.\n *\n * @param urls - Array of URLs to filter\n * @param policy - SSRF policy\n * @returns Array of safe URLs\n */\nexport function filterSafeUrls(\n  urls: string[],\n  policy?: SSRFPolicy,\n): string[] {\n  return urls.filter((url) => isURLSafe(url, policy).safe);\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -128,7 +128,23 @@ function streamingUnzipSync(data, limits = DEFAULT_ZIP_LIMITS) {
       if (unsafePathHandling === "warn" && limits.onUnsafePath) {
         limits.onUnsafePath(file.name, reason);
       }
-      file.ondata = () => {
+      file.ondata = (err, chunk, _final) => {
+        if (error) return;
+        if (err) {
+          error = err;
+          return;
+        }
+        if (chunk && chunk.length > 0) {
+          totalBytes += chunk.length;
+          if (totalBytes > limits.maxTotalSize) {
+            error = new ZipPreflightError(
+              `Total actual size ${totalBytes} exceeds limit ${limits.maxTotalSize}`,
+              totalBytes,
+              limits.maxTotalSize
+            );
+            file.terminate();
+          }
+        }
       };
       file.start();
       return;
@@ -588,22 +604,24 @@ var ExtractedAssetSchema = import_zod.z.object({
   mimeType: import_zod.z.string()
 });
 var CCv2LorebookEntrySchema = import_zod2.z.object({
-  keys: import_zod2.z.array(import_zod2.z.string()),
+  keys: import_zod2.z.array(import_zod2.z.string()).optional(),
+  // Some tools use 'key' instead
   content: import_zod2.z.string(),
-  enabled: import_zod2.z.boolean(),
-  insertion_order: import_zod2.z.number().int(),
-  // Optional fields
+  enabled: import_zod2.z.boolean().default(true),
+  // Default to enabled if missing
+  insertion_order: import_zod2.z.number().int().default(0),
+  // Optional fields - be lenient with nulls since wild data has them
   extensions: import_zod2.z.record(import_zod2.z.unknown()).optional(),
-  case_sensitive: import_zod2.z.boolean().optional(),
+  case_sensitive: import_zod2.z.boolean().nullable().optional(),
   name: import_zod2.z.string().optional(),
   priority: import_zod2.z.number().int().optional(),
   id: import_zod2.z.number().int().optional(),
   comment: import_zod2.z.string().optional(),
-  selective: import_zod2.z.boolean().optional(),
+  selective: import_zod2.z.boolean().nullable().optional(),
   secondary_keys: import_zod2.z.array(import_zod2.z.string()).optional(),
-  constant: import_zod2.z.boolean().optional(),
-  position: import_zod2.z.enum(["before_char", "after_char"]).optional()
-});
+  constant: import_zod2.z.boolean().nullable().optional(),
+  position: import_zod2.z.union([import_zod2.z.enum(["before_char", "after_char"]), import_zod2.z.number().int()]).nullable().optional()
+}).passthrough();
 var CCv2CharacterBookSchema = import_zod2.z.object({
   name: import_zod2.z.string().optional(),
   description: import_zod2.z.string().optional(),
@@ -651,31 +669,34 @@ function getV2Data(card) {
   return card;
 }
 var CCv3LorebookEntrySchema = import_zod3.z.object({
-  keys: import_zod3.z.array(import_zod3.z.string()),
+  keys: import_zod3.z.array(import_zod3.z.string()).optional(),
+  // Some tools use 'key' instead
   content: import_zod3.z.string(),
-  enabled: import_zod3.z.boolean(),
-  insertion_order: import_zod3.z.number().int(),
-  // Optional fields
-  case_sensitive: import_zod3.z.boolean().optional(),
+  enabled: import_zod3.z.boolean().default(true),
+  // Default to enabled if missing
+  insertion_order: import_zod3.z.number().int().default(0),
+  // Optional fields - be lenient with nulls since wild data has them
+  case_sensitive: import_zod3.z.boolean().nullable().optional(),
   name: import_zod3.z.string().optional(),
   priority: import_zod3.z.number().int().optional(),
   id: import_zod3.z.number().int().optional(),
   comment: import_zod3.z.string().optional(),
-  selective: import_zod3.z.boolean().optional(),
+  selective: import_zod3.z.boolean().nullable().optional(),
   secondary_keys: import_zod3.z.array(import_zod3.z.string()).optional(),
-  constant: import_zod3.z.boolean().optional(),
-  position: import_zod3.z.enum(["before_char", "after_char"]).optional(),
+  constant: import_zod3.z.boolean().nullable().optional(),
+  position: import_zod3.z.union([import_zod3.z.enum(["before_char", "after_char"]), import_zod3.z.number().int()]).nullable().optional(),
   extensions: import_zod3.z.record(import_zod3.z.unknown()).optional(),
-  // v3 specific
+  // v3 specific - also lenient with types since SillyTavern uses numbers for enums
   automation_id: import_zod3.z.string().optional(),
-  role: import_zod3.z.enum(["system", "user", "assistant"]).optional(),
+  role: import_zod3.z.union([import_zod3.z.enum(["system", "user", "assistant"]), import_zod3.z.number().int()]).nullable().optional(),
   group: import_zod3.z.string().optional(),
   scan_frequency: import_zod3.z.number().int().nonnegative().optional(),
-  probability: import_zod3.z.number().min(0).max(1).optional(),
+  probability: import_zod3.z.number().min(0).max(100).optional(),
+  // Some tools use 0-100 instead of 0-1
   use_regex: import_zod3.z.boolean().optional(),
   depth: import_zod3.z.number().int().nonnegative().optional(),
-  selective_logic: import_zod3.z.enum(["AND", "NOT"]).optional()
-});
+  selective_logic: import_zod3.z.union([import_zod3.z.enum(["AND", "NOT"]), import_zod3.z.number().int()]).optional()
+}).passthrough();
 var CCv3CharacterBookSchema = import_zod3.z.object({
   name: import_zod3.z.string().optional(),
   description: import_zod3.z.string().optional(),
@@ -8111,8 +8132,10 @@ function voxtaToCCv3(character, books) {
       };
     }
   }
-  const creationDate = character.DateCreated ? Math.floor(new Date(character.DateCreated).getTime() / 1e3) : void 0;
-  const modificationDate = character.DateModified ? Math.floor(new Date(character.DateModified).getTime() / 1e3) : void 0;
+  const rawCreationDate = character.DateCreated ? Math.floor(new Date(character.DateCreated).getTime() / 1e3) : void 0;
+  const rawModificationDate = character.DateModified ? Math.floor(new Date(character.DateModified).getTime() / 1e3) : void 0;
+  const creationDate = rawCreationDate !== void 0 && rawCreationDate >= 0 ? rawCreationDate : void 0;
+  const modificationDate = rawModificationDate !== void 0 && rawModificationDate >= 0 ? rawModificationDate : void 0;
   const card = {
     spec: "chara_card_v3",
     spec_version: "3.0",
@@ -8353,6 +8376,11 @@ var DELTA_MAX_TOTAL_SIZE = 500 * 1024 * 1024;
 var DELTA_MAX_FILE_SIZE = 50 * 1024 * 1024;
 
 // ../normalizer/dist/index.js
+function normalizePosition(position) {
+  if (position === void 0 || position === null) return "before_char";
+  if (typeof position === "string") return position;
+  return position;
+}
 function convertLorebookEntry(entry, index) {
   return {
     keys: entry.keys || [],
@@ -8368,7 +8396,7 @@ function convertLorebookEntry(entry, index) {
     selective: entry.selective ?? false,
     secondary_keys: entry.secondary_keys || [],
     constant: entry.constant ?? false,
-    position: entry.position || "before_char"
+    position: normalizePosition(entry.position)
   };
 }
 function convertCharacterBook(book) {
@@ -8531,6 +8559,43 @@ var DEFAULT_OPTIONS3 = {
   maxTotalSize: 500 * 1024 * 1024,
   extractAssets: true
 };
+var ASSET_PREFIX_VARIANTS = [
+  { prefix: "__asset:", format: "CCv3 (SillyTavern)" },
+  { prefix: "asset:", format: "CCv2/CCv3 common" },
+  { prefix: "pngchunk:", format: "Explicit PNG chunk" },
+  { prefix: "chara-ext-asset_:", format: "RisuAI (with colon)" },
+  { prefix: "chara-ext-asset_", format: "RisuAI" },
+  { prefix: "__asset_", format: "Legacy underscore variant" }
+];
+function isChunkReference(uri) {
+  return ASSET_PREFIX_VARIANTS.some(({ prefix }) => uri.startsWith(prefix)) || !uri.includes(":");
+}
+function stripAssetPrefix(uri) {
+  for (const { prefix } of ASSET_PREFIX_VARIANTS) {
+    if (uri.startsWith(prefix)) {
+      return uri.substring(prefix.length);
+    }
+  }
+  return uri;
+}
+function generateChunkKeyCandidates(assetId, originalUri) {
+  return [
+    assetId,
+    // Plain ID: "0"
+    originalUri,
+    // Original URI: "__asset:0"
+    `asset:${assetId}`,
+    // Common format
+    `__asset:${assetId}`,
+    // CCv3 format
+    `__asset_${assetId}`,
+    // Legacy underscore variant
+    `chara-ext-asset_${assetId}`,
+    // RisuAI format
+    `chara-ext-asset_:${assetId}`
+    // RisuAI format with colon
+  ];
+}
 function estimateBase64DecodedSize(base64Length) {
   return Math.ceil(base64Length * 0.75);
 }
@@ -8598,39 +8663,22 @@ function parsePng(data, options) {
   if (extracted.extraChunks && options.extractAssets && card.data.assets) {
     const usedChunks = /* @__PURE__ */ new Set();
     const chunkMap = /* @__PURE__ */ new Map();
+    const risuIndexPrefixes = ASSET_PREFIX_VARIANTS.filter((v) => v.prefix.startsWith("chara-ext-asset_"));
     for (const chunk of extracted.extraChunks) {
       chunkMap.set(chunk.keyword, chunk);
-      if (chunk.keyword.startsWith("chara-ext-asset_")) {
-        const suffix = chunk.keyword.replace("chara-ext-asset_", "");
-        chunkMap.set(suffix, chunk);
-        if (suffix.startsWith(":")) {
-          chunkMap.set(suffix.substring(1), chunk);
+      for (const { prefix } of risuIndexPrefixes) {
+        if (chunk.keyword.startsWith(prefix)) {
+          const suffix = chunk.keyword.substring(prefix.length);
+          chunkMap.set(suffix, chunk);
+          break;
         }
       }
     }
     for (const descriptor of card.data.assets) {
       if (!descriptor.uri) continue;
-      if (descriptor.uri.startsWith("__asset:") || descriptor.uri.startsWith("asset:") || descriptor.uri.startsWith("pngchunk:") || !descriptor.uri.includes(":")) {
-        let assetId = descriptor.uri;
-        if (assetId.startsWith("__asset:")) assetId = assetId.substring(8);
-        else if (assetId.startsWith("asset:")) assetId = assetId.substring(6);
-        else if (assetId.startsWith("pngchunk:")) assetId = assetId.substring(9);
-        const candidates = [
-          assetId,
-          // "0"
-          descriptor.uri,
-          // "__asset:0"
-          `asset:${assetId}`,
-          // "asset:0"
-          `__asset:${assetId}`,
-          // "__asset:0"
-          `__asset_${assetId}`,
-          // "__asset_0"
-          `chara-ext-asset_${assetId}`,
-          // "chara-ext-asset_0"
-          `chara-ext-asset_:${assetId}`
-          // "chara-ext-asset_:0"
-        ];
+      if (isChunkReference(descriptor.uri)) {
+        const assetId = stripAssetPrefix(descriptor.uri);
+        const candidates = generateChunkKeyCandidates(assetId, descriptor.uri);
         let chunk;
         for (const candidate of candidates) {
           chunk = chunkMap.get(candidate);
@@ -8677,13 +8725,15 @@ function parsePng(data, options) {
         }
       }
     }
+    const risuPrefixes = ASSET_PREFIX_VARIANTS.filter((v) => v.prefix.startsWith("chara-ext-asset_"));
     for (const chunk of extracted.extraChunks) {
       if (!usedChunks.has(chunk.keyword)) {
         let assetId = null;
-        if (chunk.keyword.startsWith("chara-ext-asset_:")) {
-          assetId = chunk.keyword.substring("chara-ext-asset_:".length);
-        } else if (chunk.keyword.startsWith("chara-ext-asset_")) {
-          assetId = chunk.keyword.substring("chara-ext-asset_".length);
+        for (const { prefix } of risuPrefixes) {
+          if (chunk.keyword.startsWith(prefix)) {
+            assetId = chunk.keyword.substring(prefix.length);
+            break;
+          }
         }
         if (assetId) {
           try {