@vulcn/engine 0.9.2 → 0.9.3

package/dist/index.js

@@ -1,6 +1,398 @@
+// src/config.ts
+import { z } from "zod";
+var ScanConfigSchema = z.object({
+  /** Browser engine to use */
+  browser: z.enum(["chromium", "firefox", "webkit"]).default("chromium"),
+  /** Run in headless mode */
+  headless: z.boolean().default(true),
+  /** Per-step timeout in ms */
+  timeout: z.number().positive().default(3e4)
+}).default({});
+var PayloadsConfigSchema = z.object({
+  /** Payload types to use */
+  types: z.array(z.enum(["xss", "sqli", "xxe", "cmd", "redirect", "traversal"])).default(["xss"]),
+  /** Opt-in to PayloadsAllTheThings community payloads */
+  payloadbox: z.boolean().default(false),
+  /** Max payloads per type from PayloadBox */
+  limit: z.number().positive().default(100),
+  /** Path to custom payload YAML file (relative to project root) */
+  custom: z.string().nullable().default(null)
+}).default({});
+var XssDetectionSchema = z.object({
+  /** Monitor alert/confirm/prompt dialogs */
+  dialogs: z.boolean().default(true),
+  /** Monitor console.log markers */
+  console: z.boolean().default(true),
+  /** Console marker prefix */
+  consoleMarker: z.string().default("VULCN_XSS:"),
+  /** Check for injected <script> elements */
+  domMutation: z.boolean().default(false),
+  /** Finding severity level */
+  severity: z.enum(["critical", "high", "medium", "low"]).default("high"),
+  /** Text patterns to match in alert messages */
+  alertPatterns: z.array(z.string()).default([
+    "XSS",
+    "1",
+    "document.domain",
+    "document.cookie",
+    "vulcn",
+    "pwned"
+  ])
+}).default({});
+var ReflectionSeveritySchema = z.object({
+  script: z.enum(["critical", "high", "medium", "low"]).default("critical"),
+  attribute: z.enum(["critical", "high", "medium", "low"]).default("medium"),
+  body: z.enum(["critical", "high", "medium", "low"]).default("low")
+}).default({});
+var ReflectionContextsSchema = z.object({
+  script: z.boolean().default(true),
+  attribute: z.boolean().default(true),
+  body: z.boolean().default(true)
+}).default({});
+var ReflectionDetectionSchema = z.object({
+  /** Enable reflection detection */
+  enabled: z.boolean().default(true),
+  /** Minimum payload length to check */
+  minLength: z.number().positive().default(4),
+  /** Which HTML contexts to check for reflections */
+  contexts: ReflectionContextsSchema,
+  /** Severity per context */
+  severity: ReflectionSeveritySchema
+}).default({});
+var DetectionConfigSchema = z.object({
+  /** XSS detection settings */
+  xss: XssDetectionSchema,
+  /** Reflection detection settings */
+  reflection: ReflectionDetectionSchema,
+  /** Enable passive security checks (headers, cookies, info-disclosure) */
+  passive: z.boolean().default(true)
+}).default({});
+var CrawlConfigSchema = z.object({
+  /** Maximum crawl depth */
+  depth: z.number().nonnegative().default(2),
+  /** Maximum pages to visit */
+  maxPages: z.number().positive().default(20),
+  /** Stay on same origin */
+  sameOrigin: z.boolean().default(true),
+  /** Per-page timeout in ms */
+  timeout: z.number().positive().default(1e4)
+}).default({});
+var ReportConfigSchema = z.object({
+  /** Report format to generate */
+  format: z.enum(["html", "json", "yaml", "sarif", "all"]).nullable().default(null)
+}).default({});
+var FormAuthSchema = z.object({
+  strategy: z.literal("form"),
+  /** Login page URL */
+  loginUrl: z.string().url().optional(),
+  /** CSS selector for username field */
+  userSelector: z.string().nullable().default(null),
+  /** CSS selector for password field */
+  passSelector: z.string().nullable().default(null)
+});
+var HeaderAuthSchema = z.object({
+  strategy: z.literal("header"),
+  /** Headers to include in requests */
+  headers: z.record(z.string())
+});
+var AuthConfigSchema = z.discriminatedUnion("strategy", [FormAuthSchema, HeaderAuthSchema]).nullable().default(null);
+var VulcnProjectConfigSchema = z.object({
+  /** Target URL to scan */
+  target: z.string().url().optional(),
+  /** Scan settings (browser, headless, timeout) */
+  scan: ScanConfigSchema,
+  /** Payload configuration */
+  payloads: PayloadsConfigSchema,
+  /** Detection configuration */
+  detection: DetectionConfigSchema,
+  /** Crawl configuration */
+  crawl: CrawlConfigSchema,
+  /** Report configuration */
+  report: ReportConfigSchema,
+  /** Authentication configuration */
+  auth: AuthConfigSchema
+});
+function parseProjectConfig(raw) {
+  return VulcnProjectConfigSchema.parse(raw);
+}
+var DEFAULT_PROJECT_CONFIG = {
+  target: "https://example.com",
+  scan: {
+    browser: "chromium",
+    headless: true,
+    timeout: 3e4
+  },
+  payloads: {
+    types: ["xss"]
+  },
+  detection: {
+    xss: {
+      dialogs: true,
+      console: true,
+      domMutation: false,
+      severity: "high"
+    },
+    reflection: {
+      enabled: true
+    },
+    passive: true
+  },
+  crawl: {
+    depth: 2,
+    maxPages: 20,
+    sameOrigin: true
+  },
+  report: {
+    format: "html"
+  }
+};
+
+// src/project.ts
+import { readFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, dirname, join } from "path";
+import YAML from "yaml";
+var CONFIG_FILENAME = ".vulcn.yml";
+var DIRS = {
+  sessions: "sessions",
+  auth: "auth",
+  reports: "reports"
+};
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir ?? process.cwd());
+  while (true) {
+    const configPath = join(dir, CONFIG_FILENAME);
+    if (existsSync(configPath)) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+function resolveProjectPaths(root) {
+  return {
+    root,
+    config: join(root, CONFIG_FILENAME),
+    sessions: join(root, DIRS.sessions),
+    auth: join(root, DIRS.auth),
+    reports: join(root, DIRS.reports)
+  };
+}
+async function loadProject(startDir) {
+  const root = findProjectRoot(startDir);
+  if (!root) {
+    throw new Error(
+      `No ${CONFIG_FILENAME} found. Run \`vulcn init\` to create one.`
+    );
+  }
+  const paths = resolveProjectPaths(root);
+  const raw = await readFile(paths.config, "utf-8");
+  let parsed;
+  try {
+    parsed = YAML.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Invalid YAML in ${paths.config}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed === null || parsed === void 0) {
+    parsed = {};
+  }
+  const config = parseProjectConfig(parsed);
+  return { config, paths };
+}
+async function loadProjectFromFile(configPath) {
+  const absPath = resolve(configPath);
+  const root = dirname(absPath);
+  const paths = resolveProjectPaths(root);
+  const raw = await readFile(absPath, "utf-8");
+  let parsed;
+  try {
+    parsed = YAML.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Invalid YAML in ${absPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed === null || parsed === void 0) {
+    parsed = {};
+  }
+  const config = parseProjectConfig(parsed);
+  return { config, paths };
+}
+async function ensureProjectDirs(paths, dirs = ["sessions"]) {
+  for (const dir of dirs) {
+    const dirPath = paths[dir];
+    if (!existsSync(dirPath)) {
+      await mkdir(dirPath, { recursive: true });
+    }
+  }
+}
+
 // src/driver-manager.ts
-import { isAbsolute, resolve } from "path";
+import { isAbsolute, resolve as resolve2 } from "path";
+import { createRequire } from "module";
 import { parse } from "yaml";
+
+// src/errors.ts
+var ErrorSeverity = /* @__PURE__ */ ((ErrorSeverity2) => {
+  ErrorSeverity2["FATAL"] = "fatal";
+  ErrorSeverity2["ERROR"] = "error";
+  ErrorSeverity2["WARN"] = "warn";
+  return ErrorSeverity2;
+})(ErrorSeverity || {});
+var VulcnError = class _VulcnError extends Error {
+  severity;
+  source;
+  context;
+  timestamp;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "VulcnError";
+    this.severity = options.severity;
+    this.source = options.source;
+    this.context = options.context;
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  }
+  /**
+   * Wrap any caught error into a VulcnError.
+   * If it's already a VulcnError, returns it as-is.
+   */
+  static from(err, defaults) {
+    if (err instanceof _VulcnError) return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new _VulcnError(message, {
+      severity: defaults.severity,
+      source: defaults.source,
+      cause: err,
+      context: defaults.context
+    });
+  }
+};
+function fatal(message, source, options) {
+  return new VulcnError(message, {
+    severity: "fatal" /* FATAL */,
+    source,
+    ...options
+  });
+}
+function error(message, source, options) {
+  return new VulcnError(message, {
+    severity: "error" /* ERROR */,
+    source,
+    ...options
+  });
+}
+function warn(message, source, options) {
+  return new VulcnError(message, {
+    severity: "warn" /* WARN */,
+    source,
+    ...options
+  });
+}
+var ErrorHandler = class {
+  errors = [];
+  listeners = [];
+  /**
+   * Handle an error based on its severity.
+   *
+   * - FATAL: logs, records, then THROWS (caller must not catch silently)
+   * - ERROR: logs and records
+   * - WARN: logs only
+   */
+  handle(err) {
+    this.errors.push(err);
+    for (const listener of this.listeners) {
+      try {
+        listener(err);
+      } catch {
+      }
+    }
+    const ctx = err.context ? ` ${JSON.stringify(err.context)}` : "";
+    switch (err.severity) {
+      case "fatal" /* FATAL */:
+        console.error(`\u274C FATAL [${err.source}] ${err.message}${ctx}`);
+        if (err.cause instanceof Error) {
+          console.error(`   Caused by: ${err.cause.message}`);
+        }
+        throw err;
+      // ← This is the whole point. FATAL stops execution.
+      case "error" /* ERROR */:
+        console.error(`\u26A0\uFE0F  ERROR [${err.source}] ${err.message}${ctx}`);
+        break;
+      case "warn" /* WARN */:
+        console.warn(`\u26A1 WARN  [${err.source}] ${err.message}${ctx}`);
+        break;
+    }
+  }
+  /**
+   * Convenience: wrap a caught error and handle it.
+   */
+  catch(err, defaults) {
+    this.handle(VulcnError.from(err, defaults));
+  }
+  // ── Query ──────────────────────────────────────────────────────────
+  /** All recorded errors (FATAL + ERROR + WARN) */
+  getAll() {
+    return [...this.errors];
+  }
+  /** Only ERROR and FATAL */
+  getErrors() {
+    return this.errors.filter(
+      (e) => e.severity === "error" /* ERROR */ || e.severity === "fatal" /* FATAL */
+    );
+  }
+  /** Were there any errors (not just warnings)? */
+  hasErrors() {
+    return this.errors.some(
+      (e) => e.severity === "error" /* ERROR */ || e.severity === "fatal" /* FATAL */
+    );
+  }
+  /** Count by severity */
+  counts() {
+    const counts = {
+      ["fatal" /* FATAL */]: 0,
+      ["error" /* ERROR */]: 0,
+      ["warn" /* WARN */]: 0
+    };
+    for (const e of this.errors) {
+      counts[e.severity]++;
+    }
+    return counts;
+  }
+  /** Human-readable summary for end-of-run reporting */
+  getSummary() {
+    if (this.errors.length === 0) return "No errors.";
+    const c = this.counts();
+    const lines = [
+      `Error Summary: ${c.fatal} fatal, ${c.error} errors, ${c.warn} warnings`
+    ];
+    for (const e of this.errors) {
+      const icon = e.severity === "fatal" /* FATAL */ ? "\u274C" : e.severity === "error" /* ERROR */ ? "\u26A0\uFE0F " : "\u26A1";
+      lines.push(`  ${icon} [${e.source}] ${e.message}`);
+    }
+    return lines.join("\n");
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────────
+  /** Subscribe to errors as they happen */
+  onError(listener) {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+  /** Reset for a new run */
+  clear() {
+    this.errors = [];
+  }
+};
+
+// src/driver-manager.ts
+var require2 = createRequire(import.meta.url);
+var { version: ENGINE_VERSION } = require2("../package.json");
 var DriverManager = class {
   drivers = /* @__PURE__ */ new Map();
   defaultDriver = null;
@@ -21,7 +413,7 @@ var DriverManager = class {
     let driver;
     let source;
     if (nameOrPath.startsWith("./") || nameOrPath.startsWith("../") || isAbsolute(nameOrPath)) {
-      const resolved = isAbsolute(nameOrPath) ? nameOrPath : resolve(process.cwd(), nameOrPath);
+      const resolved = isAbsolute(nameOrPath) ? nameOrPath : resolve2(process.cwd(), nameOrPath);
       const module = await import(resolved);
       driver = module.default || module;
       source = "local";
@@ -82,44 +474,18 @@ var DriverManager = class {
   /**
    * Parse a YAML session string into a Session object.
    *
-   * Handles both new driver-format sessions and legacy v1 sessions.
-   * Legacy sessions (those with non-namespaced step types like "click",
-   * "input", "navigate") are automatically converted to the driver format
-   * (e.g., "browser.click", "browser.input", "browser.navigate").
+   * Sessions must use the driver format with a `driver` field.
    *
    * @param yaml - Raw YAML string
-   * @param defaultDriver - Driver to assign for legacy sessions (default: "browser")
    */
-  parseSession(yaml, defaultDriver = "browser") {
+  parseSession(yaml) {
     const data = parse(yaml);
-    if (data.driver && typeof data.driver === "string") {
-      return data;
-    }
-    const steps = data.steps ?? [];
-    const convertedSteps = steps.map((step) => {
-      const type = step.type;
-      if (type.includes(".")) {
-        return step;
-      }
-      return {
-        ...step,
-        type: `${defaultDriver}.${type}`
-      };
-    });
-    return {
-      name: data.name ?? "Untitled Session",
-      driver: defaultDriver,
-      driverConfig: {
-        browser: data.browser ?? "chromium",
-        viewport: data.viewport ?? { width: 1280, height: 720 },
-        startUrl: data.startUrl
-      },
-      steps: convertedSteps,
-      metadata: {
-        recordedAt: data.recordedAt,
-        version: data.version ?? "1"
-      }
-    };
+    if (!data.driver || typeof data.driver !== "string") {
+      throw new Error(
+        "Invalid session format: missing 'driver' field. Sessions must use the driver format."
+      );
+    }
+    return data;
   }
   /**
    * Start recording with a driver
@@ -173,11 +539,12 @@ var DriverManager = class {
       page: null,
       headless: !!options.headless,
       config: {},
-      engine: { version: "0.3.0", pluginApiVersion: 1 },
+      engine: { version: ENGINE_VERSION, pluginApiVersion: 1 },
       payloads: pluginManager2.getPayloads(),
       findings,
       addFinding,
       logger,
+      errors: pluginManager2.getErrorHandler(),
       fetch: globalThis.fetch
     };
     const ctx = {
@@ -187,6 +554,7 @@ var DriverManager = class {
       findings,
       addFinding,
       logger,
+      errors: pluginManager2.getErrorHandler(),
       options: {
         ...options,
         // Provide onPageReady callback — fires plugin onRunStart hooks
@@ -201,9 +569,11 @@ var DriverManager = class {
                   config: loaded.config
                 });
               } catch (err) {
-                logger.warn(
-                  `Plugin ${loaded.plugin.name} onRunStart failed: ${err}`
-                );
+                pluginManager2.getErrorHandler().catch(err, {
+                  severity: "error" /* ERROR */,
+                  source: `plugin:${loaded.plugin.name}`,
+                  context: { hook: "onRunStart" }
+                });
               }
             }
           }
@@ -218,9 +588,11 @@ var DriverManager = class {
                   config: loaded.config
                 });
               } catch (err) {
-                logger.warn(
-                  `Plugin ${loaded.plugin.name} onBeforeClose failed: ${err}`
-                );
+                pluginManager2.getErrorHandler().catch(err, {
+                  severity: "warn" /* WARN */,
+                  source: `plugin:${loaded.plugin.name}`,
+                  context: { hook: "onBeforeClose" }
+                });
               }
             }
           }
@@ -237,7 +609,11 @@ var DriverManager = class {
             findings: result.findings
           });
         } catch (err) {
-          logger.warn(`Plugin ${loaded.plugin.name} onRunEnd failed: ${err}`);
+          pluginManager2.getErrorHandler().catch(err, {
+            severity: "fatal" /* FATAL */,
+            source: `plugin:${loaded.plugin.name}`,
+            context: { hook: "onRunEnd" }
+          });
         }
       }
     }
@@ -275,24 +651,23 @@ var DriverManager = class {
     const allErrors = [];
     const firstDriver = this.getForSession(sessions[0]);
     let sharedBrowser = null;
-    if (firstDriver.name === "browser") {
+    if (typeof firstDriver.createSharedResource === "function") {
       try {
-        const driverPkg = "@vulcn/driver-browser";
-        const { launchBrowser } = await import(
-          /* @vite-ignore */
-          driverPkg
+        const driverConfig = sessions[0].driverConfig;
+        sharedBrowser = await firstDriver.createSharedResource(
+          driverConfig,
+          options
         );
-        const browserType = sessions[0].driverConfig.browser ?? "chromium";
-        const headless = options.headless ?? true;
-        const result = await launchBrowser({
-          browser: browserType,
-          headless
+      } catch (err) {
+        pluginManager2.getErrorHandler().catch(err, {
+          severity: "warn" /* WARN */,
+          source: `driver-manager:${firstDriver.name}`,
+          context: { action: "create-shared-resource" }
         });
-        sharedBrowser = result.browser;
-      } catch {
       }
     }
     try {
+      await pluginManager2.initialize();
       await pluginManager2.callHook("onScanStart", async (hook, ctx) => {
         const scanCtx = {
           ...ctx,
@@ -302,21 +677,63 @@ var DriverManager = class {
         };
         await hook(scanCtx);
       });
-      for (const session of sessions) {
+      for (let i = 0; i < sessions.length; i++) {
+        const session = sessions[i];
+        pluginManager2.clearFindings();
+        options.onSessionStart?.(session, i, sessions.length);
         const sessionOptions = {
           ...options,
           ...sharedBrowser ? { browser: sharedBrowser } : {}
         };
-        const result = await this.execute(
-          session,
-          pluginManager2,
-          sessionOptions
-        );
+        let result;
+        if (options.timeout && options.timeout > 0) {
+          const execPromise = this.execute(
+            session,
+            pluginManager2,
+            sessionOptions
+          );
+          const timeoutPromise = new Promise(
+            (_, reject) => setTimeout(
+              () => reject(
+                new Error(
+                  `Session "${session.name}" timed out after ${options.timeout}ms`
+                )
+              ),
+              options.timeout
+            )
+          );
+          try {
+            result = await Promise.race([execPromise, timeoutPromise]);
+          } catch (err) {
+            result = {
+              findings: [],
+              stepsExecuted: 0,
+              payloadsTested: 0,
+              duration: options.timeout,
+              errors: [err instanceof Error ? err.message : String(err)]
+            };
+          }
+          execPromise.catch(() => {
+          });
+        } else {
+          try {
+            result = await this.execute(session, pluginManager2, sessionOptions);
+          } catch (err) {
+            result = {
+              findings: [],
+              stepsExecuted: 0,
+              payloadsTested: 0,
+              duration: 0,
+              errors: [err instanceof Error ? err.message : String(err)]
+            };
+          }
+        }
         results.push(result);
         allFindings.push(...result.findings);
         totalSteps += result.stepsExecuted;
         totalPayloads += result.payloadsTested;
         allErrors.push(...result.errors);
+        options.onSessionEnd?.(session, result, i, sessions.length);
       }
     } finally {
       if (sharedBrowser && typeof sharedBrowser.close === "function") {
@@ -389,124 +806,29 @@ var driverManager = new DriverManager();
 var DRIVER_API_VERSION = 1;
 
 // src/plugin-manager.ts
-import { readFile } from "fs/promises";
-import { existsSync } from "fs";
-import { resolve as resolve2, isAbsolute as isAbsolute2 } from "path";
-import YAML from "yaml";
-import { z } from "zod";
+import { createRequire as createRequire2 } from "module";
 
 // src/plugin-types.ts
 var PLUGIN_API_VERSION = 1;
 
 // src/plugin-manager.ts
-var ENGINE_VERSION = "0.2.0";
-var VulcnConfigSchema = z.object({
-  version: z.string().default("1"),
-  plugins: z.array(
-    z.object({
-      name: z.string(),
-      config: z.record(z.unknown()).optional(),
-      enabled: z.boolean().default(true)
-    })
-  ).optional(),
-  settings: z.object({
-    browser: z.enum(["chromium", "firefox", "webkit"]).optional(),
-    headless: z.boolean().optional(),
-    timeout: z.number().optional()
-  }).optional()
-});
-var PluginManager = class {
+var _require = createRequire2(import.meta.url);
+var { version: ENGINE_VERSION2 } = _require("../package.json");
+var PluginManager = class _PluginManager {
   plugins = [];
-  config = null;
   initialized = false;
+  errorHandler;
   /**
    * Shared context passed to all plugins
    */
   sharedPayloads = [];
   sharedFindings = [];
-  /**
-   * Load configuration from vulcn.config.yml
-   */
-  async loadConfig(configPath) {
-    const paths = configPath ? [configPath] : [
-      "vulcn.config.yml",
-      "vulcn.config.yaml",
-      "vulcn.config.json",
-      ".vulcnrc.yml",
-      ".vulcnrc.yaml",
-      ".vulcnrc.json"
-    ];
-    for (const path of paths) {
-      const resolved = isAbsolute2(path) ? path : resolve2(process.cwd(), path);
-      if (existsSync(resolved)) {
-        const content = await readFile(resolved, "utf-8");
-        const parsed = path.endsWith(".json") ? JSON.parse(content) : YAML.parse(content);
-        this.config = VulcnConfigSchema.parse(parsed);
-        return this.config;
-      }
-    }
-    this.config = { version: "1", plugins: [], settings: {} };
-    return this.config;
-  }
-  /**
-   * Load all plugins from config
-   */
-  async loadPlugins() {
-    if (!this.config) {
-      await this.loadConfig();
-    }
-    const pluginConfigs = this.config?.plugins || [];
-    for (const pluginConfig of pluginConfigs) {
-      if (pluginConfig.enabled === false) continue;
-      try {
-        const loaded = await this.loadPlugin(pluginConfig);
-        this.plugins.push(loaded);
-      } catch (err) {
-        console.error(
-          `Failed to load plugin ${pluginConfig.name}:`,
-          err instanceof Error ? err.message : String(err)
-        );
-      }
-    }
+  constructor(errorHandler) {
+    this.errorHandler = errorHandler ?? new ErrorHandler();
   }
-  /**
-   * Load a single plugin
-   */
-  async loadPlugin(config) {
-    const { name, config: pluginConfig = {} } = config;
-    let plugin;
-    let source;
-    if (name.startsWith("./") || name.startsWith("../") || isAbsolute2(name)) {
-      const resolved = isAbsolute2(name) ? name : resolve2(process.cwd(), name);
-      const module = await import(resolved);
-      plugin = module.default || module;
-      source = "local";
-    } else if (name.startsWith("@vulcn/")) {
-      const module = await import(name);
-      plugin = module.default || module;
-      source = "npm";
-    } else {
-      const module = await import(name);
-      plugin = module.default || module;
-      source = "npm";
-    }
-    this.validatePlugin(plugin);
-    let resolvedConfig = pluginConfig;
-    if (plugin.configSchema) {
-      try {
-        resolvedConfig = plugin.configSchema.parse(pluginConfig);
-      } catch (err) {
-        throw new Error(
-          `Invalid config for plugin ${name}: ${err instanceof Error ? err.message : String(err)}`
-        );
-      }
-    }
-    return {
-      plugin,
-      config: resolvedConfig,
-      source,
-      enabled: true
-    };
+  /** Get the error handler for post-run inspection */
+  getErrorHandler() {
+    return this.errorHandler;
   }
   /**
    * Validate plugin structure
@@ -565,6 +887,120 @@ var PluginManager = class {
     this.sharedFindings = [];
     this.initialized = false;
   }
+  /**
+   * Load the engine from a flat VulcnProjectConfig (from `.vulcn.yml`).
+   *
+   * This is the primary entry point for the new config system.
+   * Maps user-facing config keys to internal plugin configs automatically.
+   *
+   * @param config - Parsed and validated VulcnProjectConfig
+   */
+  async loadFromConfig(config) {
+    const { payloads, detection } = config;
+    if (payloads.custom) {
+      try {
+        const payloadPkg = "@vulcn/plugin-payloads";
+        const { loadFromFile } = await import(
+          /* @vite-ignore */
+          payloadPkg
+        );
+        const loaded = await loadFromFile(payloads.custom);
+        this.addPayloads(loaded);
+      } catch (err) {
+        throw new Error(
+          `Failed to load custom payloads from ${payloads.custom}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    try {
+      const payloadPkg = "@vulcn/plugin-payloads";
+      const { getCuratedPayloads, loadPayloadBox } = await import(
+        /* @vite-ignore */
+        payloadPkg
+      );
+      for (const name of payloads.types) {
+        const curated = getCuratedPayloads(name);
+        if (curated) {
+          this.addPayloads(curated);
+        }
+        if (payloads.payloadbox || !curated) {
+          try {
+            const payload = await loadPayloadBox(name, payloads.limit);
+            this.addPayloads([payload]);
+          } catch (err) {
+            if (!curated) {
+              throw new Error(
+                `No payloads for "${name}": no curated set and PayloadBox failed: ${err instanceof Error ? err.message : String(err)}`
+              );
+            }
+          }
+        }
+      }
+    } catch (err) {
+      throw new Error(
+        `Failed to load payloads: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (payloads.types.includes("xss") && !this.hasPlugin("@vulcn/plugin-detect-xss")) {
+      try {
+        const pkg = "@vulcn/plugin-detect-xss";
+        const mod = await import(
+          /* @vite-ignore */
+          pkg
+        );
+        this.addPlugin(mod.default, {
+          detectDialogs: detection.xss.dialogs,
+          detectConsole: detection.xss.console,
+          consoleMarker: detection.xss.consoleMarker,
+          detectDomMutation: detection.xss.domMutation,
+          severity: detection.xss.severity,
+          alertPatterns: detection.xss.alertPatterns
+        });
+      } catch (err) {
+        this.errorHandler.catch(err, {
+          severity: "warn" /* WARN */,
+          source: "plugin-manager:loadFromConfig",
+          context: { plugin: "@vulcn/plugin-detect-xss" }
+        });
+      }
+    }
+    const hasSqli = payloads.types.some((t) => {
+      const lower = t.toLowerCase();
+      return lower === "sqli" || lower.includes("sql");
+    });
+    if (hasSqli && !this.hasPlugin("@vulcn/plugin-detect-sqli")) {
+      try {
+        const pkg = "@vulcn/plugin-detect-sqli";
+        const mod = await import(
+          /* @vite-ignore */
+          pkg
+        );
+        this.addPlugin(mod.default);
+      } catch (err) {
+        this.errorHandler.catch(err, {
+          severity: "warn" /* WARN */,
+          source: "plugin-manager:loadFromConfig",
+          context: { plugin: "@vulcn/plugin-detect-sqli" }
+        });
+      }
+    }
+    if (detection.passive && !this.hasPlugin("@vulcn/plugin-passive")) {
+      try {
+        const pkg = "@vulcn/plugin-passive";
+        const mod = await import(
+          /* @vite-ignore */
+          pkg
+        );
+        this.addPlugin(mod.default);
+      } catch (err) {
+        this.errorHandler.catch(err, {
+          severity: "warn" /* WARN */,
+          source: "plugin-manager:loadFromConfig",
+          context: { plugin: "@vulcn/plugin-passive" }
+        });
+      }
+    }
+  }
   /**
    * Get all loaded payloads
    */
@@ -610,9 +1046,9 @@ var PluginManager = class {
   /**
    * Create base context for plugins
    */
-  createContext(pluginConfig) {
+  createContext(pluginConfig, pluginName) {
     const engineInfo = {
-      version: ENGINE_VERSION,
+      version: ENGINE_VERSION2,
       pluginApiVersion: PLUGIN_API_VERSION
     };
     return {
@@ -621,9 +1057,13 @@ var PluginManager = class {
       payloads: this.sharedPayloads,
       findings: this.sharedFindings,
       addFinding: (finding) => {
+        console.log(
+          `[DEBUG-PM] Plugin ${pluginName || "?"} adding finding: ${finding.type}`
+        );
         this.sharedFindings.push(finding);
       },
-      logger: this.createLogger("plugin"),
+      logger: this.createLogger(pluginName || "plugin"),
+      errors: this.errorHandler,
       fetch: globalThis.fetch
     };
   }
@@ -639,6 +1079,26 @@ var PluginManager = class {
       error: (msg, ...args) => console.error(prefix, msg, ...args)
     };
   }
+  // ── Hook severity classification ────────────────────────────────────
+  //
+  // Hooks that produce OUTPUT (reports, results) are FATAL on failure.
+  // Hooks that set up state are ERROR. Everything else is WARN.
+  //
+  static FATAL_HOOKS = /* @__PURE__ */ new Set([
+    "onRunEnd",
+    "onScanEnd"
+  ]);
+  static ERROR_HOOKS = /* @__PURE__ */ new Set([
+    "onInit",
+    "onRunStart",
+    "onScanStart",
+    "onAfterPayload"
+  ]);
+  hookSeverity(hookName) {
+    if (_PluginManager.FATAL_HOOKS.has(hookName)) return "fatal" /* FATAL */;
+    if (_PluginManager.ERROR_HOOKS.has(hookName)) return "error" /* ERROR */;
+    return "warn" /* WARN */;
+  }
   /**
    * Call a hook on all plugins sequentially
    */
@@ -646,15 +1106,16 @@ var PluginManager = class {
     for (const loaded of this.plugins) {
       const hook = loaded.plugin.hooks?.[hookName];
       if (hook) {
-        const ctx = this.createContext(loaded.config);
+        const ctx = this.createContext(loaded.config, loaded.plugin.name);
         ctx.logger = this.createLogger(loaded.plugin.name);
         try {
           await executor(hook, ctx);
         } catch (err) {
-          console.error(
-            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
-            err instanceof Error ? err.message : String(err)
-          );
+          this.errorHandler.catch(err, {
+            severity: this.hookSeverity(hookName),
+            source: `plugin:${loaded.plugin.name}`,
+            context: { hook: hookName }
+          });
         }
       }
     }
@@ -667,7 +1128,7 @@ var PluginManager = class {
     for (const loaded of this.plugins) {
       const hook = loaded.plugin.hooks?.[hookName];
       if (hook) {
-        const ctx = this.createContext(loaded.config);
+        const ctx = this.createContext(loaded.config, loaded.plugin.name);
         ctx.logger = this.createLogger(loaded.plugin.name);
         try {
           const result = await executor(
@@ -682,10 +1143,11 @@ var PluginManager = class {
             }
           }
         } catch (err) {
-          console.error(
-            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
-            err instanceof Error ? err.message : String(err)
-          );
+          this.errorHandler.catch(err, {
+            severity: this.hookSeverity(hookName),
+            source: `plugin:${loaded.plugin.name}`,
+            context: { hook: hookName }
+          });
         }
       }
     }
@@ -699,7 +1161,7 @@ var PluginManager = class {
     for (const loaded of this.plugins) {
       const hook = loaded.plugin.hooks?.[hookName];
       if (hook) {
-        const ctx = this.createContext(loaded.config);
+        const ctx = this.createContext(loaded.config, loaded.plugin.name);
         ctx.logger = this.createLogger(loaded.plugin.name);
         try {
           value = await executor(
@@ -708,10 +1170,11 @@ var PluginManager = class {
             ctx
           );
         } catch (err) {
-          console.error(
-            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
-            err instanceof Error ? err.message : String(err)
-          );
+          this.errorHandler.catch(err, {
+            severity: this.hookSeverity(hookName),
+            source: `plugin:${loaded.plugin.name}`,
+            context: { hook: hookName }
+          });
         }
       }
     }
@@ -797,177 +1260,40 @@ function getPassphrase(interactive) {
   );
 }
 
-// src/session.ts
-import { readFile as readFile2, writeFile, mkdir, readdir } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
-import { join, basename } from "path";
-import { parse as parse2, stringify as stringify2 } from "yaml";
-async function loadSessionDir(dirPath) {
-  const manifestPath = join(dirPath, "manifest.yml");
-  if (!existsSync2(manifestPath)) {
-    throw new Error(
-      `No manifest.yml found in ${dirPath}. Is this a v2 session directory?`
-    );
+// src/payload-types.ts
+function getSeverity(category) {
+  switch (category) {
+    case "sqli":
+    case "command-injection":
+    case "xxe":
+      return "critical";
+    case "xss":
+    case "ssrf":
+    case "path-traversal":
+      return "high";
+    case "open-redirect":
+      return "medium";
+    case "security-misconfiguration":
+      return "low";
+    case "information-disclosure":
+      return "info";
+    default:
+      return "medium";
   }
-  const manifestYaml = await readFile2(manifestPath, "utf-8");
-  const manifest = parse2(manifestYaml);
-  if (manifest.version !== "2") {
-    throw new Error(
-      `Unsupported session format version: ${manifest.version}. Expected "2".`
-    );
-  }
-  let authConfig;
-  if (manifest.auth?.configFile) {
-    const authPath = join(dirPath, manifest.auth.configFile);
-    if (existsSync2(authPath)) {
-      const authYaml = await readFile2(authPath, "utf-8");
-      authConfig = parse2(authYaml);
-    }
-  }
-  const sessions = [];
-  for (const ref of manifest.sessions) {
-    if (ref.injectable === false) continue;
-    const sessionPath = join(dirPath, ref.file);
-    if (!existsSync2(sessionPath)) {
-      console.warn(`Session file not found: ${sessionPath}, skipping`);
-      continue;
-    }
-    const sessionYaml = await readFile2(sessionPath, "utf-8");
-    const sessionData = parse2(sessionYaml);
-    const session = {
-      name: sessionData.name ?? basename(ref.file, ".yml"),
-      driver: manifest.driver,
-      driverConfig: {
-        ...manifest.driverConfig,
-        startUrl: resolveUrl(
-          manifest.target,
-          sessionData.page
-        )
-      },
-      steps: sessionData.steps ?? [],
-      metadata: {
-        recordedAt: manifest.recordedAt,
-        version: "2",
-        manifestDir: dirPath
-      }
-    };
-    sessions.push(session);
-  }
-  return { manifest, sessions, authConfig };
-}
-function isSessionDir(path) {
-  return existsSync2(join(path, "manifest.yml"));
-}
-function looksLikeSessionDir(path) {
-  return path.endsWith(".vulcn") || path.endsWith(".vulcn/");
-}
-async function saveSessionDir(dirPath, options) {
-  await mkdir(join(dirPath, "sessions"), { recursive: true });
-  const sessionRefs = [];
-  for (const session of options.sessions) {
-    const safeName = slugify(session.name);
-    const fileName = `sessions/${safeName}.yml`;
-    const sessionPath = join(dirPath, fileName);
-    const startUrl = session.driverConfig.startUrl;
-    const page = startUrl ? startUrl.replace(options.target, "").replace(/^\//, "/") : void 0;
-    const sessionData = {
-      name: session.name,
-      ...page ? { page } : {},
-      steps: session.steps
-    };
-    await writeFile(sessionPath, stringify2(sessionData), "utf-8");
-    const hasInjectable = session.steps.some(
-      (s) => s.type === "browser.input" && s.injectable !== false
-    );
-    sessionRefs.push({
-      file: fileName,
-      injectable: hasInjectable
-    });
-  }
-  if (options.authConfig) {
-    await mkdir(join(dirPath, "auth"), { recursive: true });
-    await writeFile(
-      join(dirPath, "auth", "config.yml"),
-      stringify2(options.authConfig),
-      "utf-8"
-    );
-  }
-  if (options.encryptedState) {
-    await mkdir(join(dirPath, "auth"), { recursive: true });
-    await writeFile(
-      join(dirPath, "auth", "state.enc"),
-      options.encryptedState,
-      "utf-8"
-    );
-  }
-  if (options.requests && options.requests.length > 0) {
-    await mkdir(join(dirPath, "requests"), { recursive: true });
-    for (const req of options.requests) {
-      const safeName = slugify(req.sessionName);
-      await writeFile(
-        join(dirPath, "requests", `${safeName}.json`),
-        JSON.stringify(req, null, 2),
-        "utf-8"
-      );
-    }
-  }
-  const manifest = {
-    version: "2",
-    name: options.name,
-    target: options.target,
-    recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    driver: options.driver,
-    driverConfig: options.driverConfig,
-    ...options.authConfig ? {
-      auth: {
-        strategy: options.authConfig.strategy,
-        configFile: "auth/config.yml",
-        stateFile: options.encryptedState ? "auth/state.enc" : void 0,
-        loggedInIndicator: options.authConfig.loggedInIndicator,
-        loggedOutIndicator: options.authConfig.loggedOutIndicator
-      }
-    } : {},
-    sessions: sessionRefs,
-    scan: {
-      tier: "auto",
-      parallel: 1,
-      timeout: 12e4
-    }
-  };
-  await writeFile(join(dirPath, "manifest.yml"), stringify2(manifest), "utf-8");
-}
-async function readAuthState(dirPath) {
-  const statePath = join(dirPath, "auth", "state.enc");
-  if (!existsSync2(statePath)) return null;
-  return readFile2(statePath, "utf-8");
-}
-async function readCapturedRequests(dirPath) {
-  const requestsDir = join(dirPath, "requests");
-  if (!existsSync2(requestsDir)) return [];
-  const files = await readdir(requestsDir);
-  const requests = [];
-  for (const file of files) {
-    if (!file.endsWith(".json")) continue;
-    const content = await readFile2(join(requestsDir, file), "utf-8");
-    requests.push(JSON.parse(content));
-  }
-  return requests;
-}
-function resolveUrl(target, page) {
-  if (!page) return target;
-  if (page.startsWith("http")) return page;
-  const base = target.replace(/\/$/, "");
-  const path = page.startsWith("/") ? page : `/${page}`;
-  return `${base}${path}`;
-}
-function slugify(text) {
-  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
 }
 export {
+  CONFIG_FILENAME,
+  DEFAULT_PROJECT_CONFIG,
+  DIRS,
   DRIVER_API_VERSION,
   DriverManager,
+  ENGINE_VERSION,
+  ErrorHandler,
+  ErrorSeverity,
   PLUGIN_API_VERSION,
   PluginManager,
+  VulcnError,
+  VulcnProjectConfigSchema,
   decrypt,
   decryptCredentials,
   decryptStorageState,
@@ -975,13 +1301,17 @@ export {
   encrypt,
   encryptCredentials,
   encryptStorageState,
+  ensureProjectDirs,
+  error,
+  fatal,
+  findProjectRoot,
   getPassphrase,
-  isSessionDir,
-  loadSessionDir,
-  looksLikeSessionDir,
+  getSeverity,
+  loadProject,
+  loadProjectFromFile,
+  parseProjectConfig,
   pluginManager,
-  readAuthState,
-  readCapturedRequests,
-  saveSessionDir
+  resolveProjectPaths,
+  warn
 };
 //# sourceMappingURL=index.js.map