@bytechain.cn/colamd-themes 0.3.0 → 0.3.1

package/src/extractors/url-extractor.ts

@@ -56,11 +56,65 @@ export class UrlExtractor implements Extractor {
     return /^https?:\/\//i.test(source);
   }
 
+  /**
+   * Validate URL to prevent SSRF attacks and ensure security.
+   * - Only allows http/https protocols
+   * - Blocks private network addresses (localhost, 10.x, 172.16-31.x, 192.168.x, 169.254.x)
+   */
+  private validateUrl(url: string): void {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new Error(`Invalid URL format: ${url}`);
+    }
+
+    // Protocol whitelist
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+      throw new Error(`Unsupported protocol "${parsed.protocol}". Only HTTP and HTTPS are allowed.`);
+    }
+
+    // Block private network ranges to prevent SSRF
+    const hostname = parsed.hostname.toLowerCase();
+    const isPrivate =
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "::1" ||
+      hostname === "[::1]" ||
+      hostname.startsWith("10.") ||
+      hostname.startsWith("172.16.") ||
+      hostname.startsWith("172.17.") ||
+      hostname.startsWith("172.18.") ||
+      hostname.startsWith("172.19.") ||
+      hostname.startsWith("172.20.") ||
+      hostname.startsWith("172.21.") ||
+      hostname.startsWith("172.22.") ||
+      hostname.startsWith("172.23.") ||
+      hostname.startsWith("172.24.") ||
+      hostname.startsWith("172.25.") ||
+      hostname.startsWith("172.26.") ||
+      hostname.startsWith("172.27.") ||
+      hostname.startsWith("172.28.") ||
+      hostname.startsWith("172.29.") ||
+      hostname.startsWith("172.30.") ||
+      hostname.startsWith("172.31.") ||
+      hostname.startsWith("192.168.") ||
+      hostname.startsWith("169.254.");
+
+    if (isPrivate) {
+      throw new Error(`Private network access denied: ${hostname}. Only public URLs are allowed for security reasons.`);
+    }
+  }
+
   async extract(source: string): Promise<ThemeStyle> {
+    this.validateUrl(source);
+
     const response = await axios.get(source, {
-      headers: { "User-Agent": "ColaMD-Themes/1.0 (Theme Extractor)" },
+      headers: { "User-Agent": "Mozilla/5.0 (compatible; ColaMD-Themes/1.0)" },
       timeout: 15000,
-      maxRedirects: 5,
+      maxRedirects: 3,
+      maxContentLength: 10 * 1024 * 1024,
+      responseType: "text",
     });
 
     const contentType = String(response.headers["content-type"] || "");

package/src/generator.ts

@@ -1,7 +1,7 @@
 /** CSS theme file generator — v3.0 seed palette pipeline. */
 
 import Handlebars from "handlebars";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
 import { join, dirname, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ThemeStyle } from "./models.js";
@@ -20,14 +20,95 @@ Handlebars.registerHelper("rgba", (hex: unknown, alpha: unknown) => {
   return toRgba(String(hex), Number(alpha));
 });
 
-let compiledTemplate: HandlebarsTemplateDelegate<ThemeStyle> | null = null;
+// ── Template Cache with Size Limits and Auto-Invalidation ──
 
-function getTemplate(): HandlebarsTemplateDelegate<ThemeStyle> {
-  if (!compiledTemplate) {
-    const source = readFileSync(templatePath, "utf-8");
-    compiledTemplate = Handlebars.compile(source, { noEscape: true });
+interface CachedTemplate {
+  compiled: HandlebarsTemplateDelegate<ThemeStyle>;
+  mtimeMs: number;
+  compiledAt: number;
+}
+
+const TEMPLATE_CACHE_MAX_SIZE = 10;
+const TEMPLATE_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const templateCache = new Map<string, CachedTemplate>();
+
+/**
+ * Get or compile a Handlebars template with caching.
+ *
+ * Features:
+ * - LRU-style cache (max 10 templates)
+ * - File modification time detection for auto-invalidation
+ * - TTL-based expiration (30 minutes)
+ * - Automatic cleanup of expired entries on access
+ */
+function getTemplate(path?: string): HandlebarsTemplateDelegate<ThemeStyle> {
+  const key = path || templatePath;
+
+  // Check cache hit
+  const cached = templateCache.get(key);
+  if (cached) {
+    // Check TTL expiration
+    if (Date.now() - cached.compiledAt > TEMPLATE_CACHE_TTL_MS) {
+      templateCache.delete(key);
+    }
+    // Check file modification time
+    else {
+      try {
+        const stats = statSync(key);
+        if (stats.mtimeMs > cached.mtimeMs) {
+          templateCache.delete(key);
+        } else {
+          return cached.compiled;
+        }
+      } catch {
+        return cached.compiled;
+      }
+    }
+  }
+
+  // Enforce max cache size (evict oldest entry)
+  if (templateCache.size >= TEMPLATE_CACHE_MAX_SIZE) {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [k, v] of templateCache.entries()) {
+      if (v.compiledAt < oldestTime) {
+        oldestTime = v.compiledAt;
+        oldestKey = k;
+      }
+    }
+
+    if (oldestKey) {
+      templateCache.delete(oldestKey);
+    }
   }
-  return compiledTemplate;
+
+  // Compile new template
+  const source = readFileSync(key, "utf-8");
+  const compiled = Handlebars.compile(source, { noEscape: true });
+
+  // Get modification time for invalidation
+  let mtimeMs = 0;
+  try {
+    mtimeMs = statSync(key).mtimeMs;
+  } catch {
+    mtimeMs = Date.now();
+  }
+
+  templateCache.set(key, {
+    compiled,
+    mtimeMs,
+    compiledAt: Date.now(),
+  });
+
+  return compiled;
+}
+
+/**
+ * Clear all cached templates to free memory.
+ */
+export function clearTemplateCache(): void {
+  templateCache.clear();
 }
 
 // ── Pipeline ──

package/src/renderer.ts

@@ -220,8 +220,10 @@ export class ColamdRenderer {
     const pdfPage = await this.browser!.newPage();
     await pdfPage.setContent(html, { waitUntil: "load", timeout: 30000 });
 
-    // Emulate screen media to preserve theme colors
-    await pdfPage.emulateMediaType("screen");
+    // NOTE: Do NOT use emulateMediaType("screen") here.
+    // The CSS template includes comprehensive @media print rules (SECTION 6)
+    // with !important declarations and print-color-adjust: exact for proper styling.
+    // Using screen mode would prevent these print-specific styles from applying.
 
     const pdfBuffer = await pdfPage.pdf({
       format: options.format ?? "A4",
@@ -233,17 +235,26 @@ export class ColamdRenderer {
     return Buffer.from(pdfBuffer);
   }
 
-  /** Shut down the browser and local server. */
+  /** Shut down the browser and local server with proper resource cleanup. */
   async close(): Promise<void> {
-    if (this.browser) {
-      await this.browser.close();
-      this.browser = null;
-      this.page = null;
+    try {
+      // Explicitly close page first to prevent zombie processes
+      if (this.page) {
+        await this.page.close().catch(() => {});
+        this.page = null;
+      }
+
+      if (this.browser) {
+        await this.browser.close();
+        this.browser = null;
+      }
+    } finally {
       this.ready = false;
-    }
-    if (this.server) {
-      await this.server.close();
-      this.server = null;
+
+      if (this.server) {
+        await this.server.close();
+        this.server = null;
+      }
     }
   }
 }

package/src/theme-store.ts

@@ -2,15 +2,20 @@
  * Theme configuration persistence.
  *
  * Stores default theme and registered custom themes in ~/.colamd-themes/config.json
+ * Uses async file I/O to avoid blocking the event loop.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdir, readFile, writeFile, access } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { join, basename } from "node:path";
 import { homedir } from "node:os";
 
 const CONFIG_DIR = join(homedir(), ".colamd-themes");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
+/** Maximum allowed CSS file size (1MB) to prevent OOM attacks */
+const MAX_CSS_SIZE = 1024 * 1024;
+
 /** Built-in themes provided by @bytechain.cn/colamd */
 export const BUILTIN_THEMES = ["light", "dark", "elegant", "newsprint"] as const;
 export type BuiltinTheme = (typeof BUILTIN_THEMES)[number];
@@ -22,30 +27,35 @@ export interface ThemeConfig {
   themes: Record<string, string>;
 }
 
-function readConfig(): ThemeConfig {
-  if (!existsSync(CONFIG_FILE)) return { defaultTheme: "elegant", themes: {} };
+async function readConfig(): Promise<ThemeConfig> {
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8")) as ThemeConfig;
+    await access(CONFIG_FILE);
+    const data = await readFile(CONFIG_FILE, "utf-8");
+    return JSON.parse(data) as ThemeConfig;
   } catch {
     return { defaultTheme: "elegant", themes: {} };
   }
 }
 
-function writeConfig(config: ThemeConfig): void {
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+async function writeConfig(config: ThemeConfig): Promise<void> {
+  try {
+    await access(CONFIG_DIR);
+  } catch {
+    await mkdir(CONFIG_DIR, { recursive: true });
+  }
+  await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
 }
 
 /** Get the full config. */
-export function getConfig(): ThemeConfig {
+export async function getConfig(): Promise<ThemeConfig> {
   return readConfig();
 }
 
 /** Set the default theme (built-in name or registered custom name). */
-export function setDefaultTheme(name: string): void {
-  const config = readConfig();
+export async function setDefaultTheme(name: string): Promise<void> {
+  const config = await readConfig();
   config.defaultTheme = name;
-  writeConfig(config);
+  await writeConfig(config);
 }
 
 /**
@@ -53,21 +63,64 @@ export function setDefaultTheme(name: string): void {
  * @param name  Unique name (will be prefixed with "custom:" when applied)
  * @param cssPath  Absolute path to the CSS file
  */
-export function registerTheme(name: string, cssPath: string): void {
-  const config = readConfig();
+export async function registerTheme(name: string, cssPath: string): Promise<void> {
+  const config = await readConfig();
   config.themes[name] = cssPath;
-  writeConfig(config);
+  await writeConfig(config);
 }
 
 /** Remove a registered custom theme. */
-export function unregisterTheme(name: string): boolean {
-  const config = readConfig();
+export async function unregisterTheme(name: string): Promise<boolean> {
+  const config = await readConfig();
   if (!(name in config.themes)) return false;
   delete config.themes[name];
-  writeConfig(config);
+  await writeConfig(config);
   return true;
 }
 
+/**
+ * Sanitize theme name from file path.
+ * Removes special characters and limits length to prevent injection.
+ */
+function sanitizeName(path: string): string {
+  return basename(path, ".css")
+    .replace(/[^a-zA-Z0-9_-]/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 50) || "custom";
+}
+
+/**
+ * Validate CSS file before reading.
+ * Checks extension, size, and basic content validity.
+ */
+async function validateCssFile(filePath: string): Promise<void> {
+  // Check file extension
+  if (!filePath.toLowerCase().endsWith(".css")) {
+    throw new Error(`Theme file must have .css extension: ${filePath}`);
+  }
+
+  // Check file size (synchronous stat is acceptable for metadata)
+  let stats;
+  try {
+    stats = statSync(filePath);
+  } catch {
+    throw new Error(`Cannot access theme file: ${filePath}`);
+  }
+
+  if (stats.size > MAX_CSS_SIZE) {
+    throw new Error(
+      `Theme file too large (${(stats.size / 1024).toFixed(1)}KB). ` +
+      `Maximum size: ${(MAX_CSS_SIZE / 1024).toFixed(0)}MB`
+    );
+  }
+
+  // Read and validate content
+  const content = await readFile(filePath, "utf-8");
+  if (content.length < 10) {
+    throw new Error(`Theme file appears to be empty or invalid: ${filePath}`);
+  }
+}
+
 /**
  * Resolve a theme name to the arguments needed by the ColaMD renderer.
  *
@@ -75,20 +128,19 @@ export function unregisterTheme(name: string): boolean {
  * @returns { themeName, customCSS? } — themeName is either a built-in name
  *          or "custom:<name>"; customCSS is the CSS content for custom themes.
  */
-export function resolveTheme(name?: string): {
+export async function resolveTheme(name?: string): Promise<{
   themeName: string;
   customCSS?: string;
-} {
-  const config = readConfig();
+}> {
+  const config = await readConfig();
   const resolved = name ?? config.defaultTheme;
 
   // Check if it's a registered custom theme
   if (config.themes[resolved]) {
     const cssPath = config.themes[resolved];
-    if (!existsSync(cssPath)) {
-      throw new Error(`Custom theme CSS file not found: ${cssPath}`);
-    }
-    return { themeName: `custom:${resolved}`, customCSS: readFileSync(cssPath, "utf-8") };
+    await validateCssFile(cssPath);
+    const customCSS = await readFile(cssPath, "utf-8");
+    return { themeName: `custom:${resolved}`, customCSS };
   }
 
   // Check if it's a built-in theme
@@ -97,16 +149,22 @@ export function resolveTheme(name?: string): {
   }
 
   // Treat as a direct CSS file path
-  if (existsSync(resolved)) {
-    const nameFromPath = resolved.replace(/\.css$/i, "").split("/").pop() ?? "custom";
-    return {
-      themeName: `custom:${nameFromPath}`,
-      customCSS: readFileSync(resolved, "utf-8"),
-    };
+  try {
+    await access(resolved);
+  } catch {
+    throw new Error(
+      `Unknown theme: "${resolved}". Use a built-in theme (${BUILTIN_THEMES.join(", ")}), ` +
+      `a registered custom theme, or a path to a .css file.`
+    );
   }
 
-  throw new Error(
-    `Unknown theme: "${resolved}". Use a built-in theme (${BUILTIN_THEMES.join(", ")}), ` +
-    `a registered custom theme, or a path to a .css file.`
-  );
+  // Validate and read direct CSS file
+  await validateCssFile(resolved);
+  const nameFromPath = sanitizeName(resolved);
+  const customCSS = await readFile(resolved, "utf-8");
+
+  return {
+    themeName: `custom:${nameFromPath}`,
+    customCSS,
+  };
 }

package/src/utils/cli-utils.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared utility functions for CLI commands.
+ * Provides consistent file path resolution and error handling.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve, isAbsolute, basename } from "node:path";
+
+/**
+ * Resolve input file path with validation.
+ * Converts relative paths to absolute and checks existence.
+ *
+ * @param input  File path provided by user
+ * @returns Resolved absolute path
+ * @throws Error if file does not exist
+ */
+export function resolveInputPath(input: string): string {
+  const path = isAbsolute(input) ? input : resolve(process.cwd(), input);
+  if (!existsSync(path)) {
+    throw new Error(`File not found: ${path}`);
+  }
+  return path;
+}
+
+/**
+ * Resolve output file path with sensible defaults.
+ * If output path is not specified, derives it from input path by replacing extension.
+ *
+ * @param inputPath  Resolved absolute input path
+ * @param output  Optional explicit output path
+ * @param ext  Target extension (default: ".html")
+ * @returns Resolved absolute output path
+ */
+export function resolveOutputPath(inputPath: string, output?: string, ext = ".html"): string {
+  if (output) {
+    return isAbsolute(output) ? output : resolve(process.cwd(), output);
+  }
+  return inputPath.replace(/\.md$/i, ext);
+}
+
+/**
+ * Get base filename without extension for use as document title.
+ *
+ * @param filePath  Absolute or relative file path
+ * @returns Filename without extension
+ */
+export function getDocumentTitle(filePath: string): string {
+  return basename(filePath, ".md");
+}
+
+/**
+ * Standard error codes for CLI operations.
+ * Enables consistent error handling across all commands.
+ */
+export enum ErrorCode {
+  /** Input file not found */
+  FILE_NOT_FOUND = 1,
+  /** Theme resolution failed */
+  THEME_ERROR = 2,
+  /** Rendering/export failed */
+  RENDER_ERROR = 3,
+  /** Invalid arguments or configuration */
+  INVALID_INPUT = 4,
+  /** Unknown/unexpected error */
+  UNKNOWN = 99,
+}
+
+/**
+ * Custom error class for CLI operations with structured error codes.
+ * Replaces direct process.exit() calls for better error propagation.
+ */
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode = ErrorCode.UNKNOWN,
+    public cause?: Error
+  ) {
+    super(message);
+    this.name = "CLIError";
+    if (cause) {
+      this.stack = `${this.message}\nCaused by: ${cause.stack}`;
+    }
+  }
+}