@vulcn/engine 0.9.2 → 0.9.3

package/dist/index.d.ts

@@ -1,5 +1,479 @@
 import { z } from 'zod';
 
+/**
+ * Vulcn Project Configuration — `.vulcn.yml` schema
+ *
+ * Single source of truth for all Vulcn configuration.
+ * The CLI is a thin layer that passes this config to the engine.
+ * Plugin names never appear here — the engine maps flat keys to plugins internally.
+ */
+
+declare const VulcnProjectConfigSchema: z.ZodObject<{
+    /** Target URL to scan */
+    target: z.ZodOptional<z.ZodString>;
+    /** Scan settings (browser, headless, timeout) */
+    scan: z.ZodDefault<z.ZodObject<{
+        /** Browser engine to use */
+        browser: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
+        /** Run in headless mode */
+        headless: z.ZodDefault<z.ZodBoolean>;
+        /** Per-step timeout in ms */
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        browser: "chromium" | "firefox" | "webkit";
+        headless: boolean;
+        timeout: number;
+    }, {
+        browser?: "chromium" | "firefox" | "webkit" | undefined;
+        headless?: boolean | undefined;
+        timeout?: number | undefined;
+    }>>;
+    /** Payload configuration */
+    payloads: z.ZodDefault<z.ZodObject<{
+        /** Payload types to use */
+        types: z.ZodDefault<z.ZodArray<z.ZodEnum<["xss", "sqli", "xxe", "cmd", "redirect", "traversal"]>, "many">>;
+        /** Opt-in to PayloadsAllTheThings community payloads */
+        payloadbox: z.ZodDefault<z.ZodBoolean>;
+        /** Max payloads per type from PayloadBox */
+        limit: z.ZodDefault<z.ZodNumber>;
+        /** Path to custom payload YAML file (relative to project root) */
+        custom: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        custom: string | null;
+        types: ("xss" | "sqli" | "xxe" | "cmd" | "redirect" | "traversal")[];
+        payloadbox: boolean;
+        limit: number;
+    }, {
+        custom?: string | null | undefined;
+        types?: ("xss" | "sqli" | "xxe" | "cmd" | "redirect" | "traversal")[] | undefined;
+        payloadbox?: boolean | undefined;
+        limit?: number | undefined;
+    }>>;
+    /** Detection configuration */
+    detection: z.ZodDefault<z.ZodObject<{
+        /** XSS detection settings */
+        xss: z.ZodDefault<z.ZodObject<{
+            /** Monitor alert/confirm/prompt dialogs */
+            dialogs: z.ZodDefault<z.ZodBoolean>;
+            /** Monitor console.log markers */
+            console: z.ZodDefault<z.ZodBoolean>;
+            /** Console marker prefix */
+            consoleMarker: z.ZodDefault<z.ZodString>;
+            /** Check for injected <script> elements */
+            domMutation: z.ZodDefault<z.ZodBoolean>;
+            /** Finding severity level */
+            severity: z.ZodDefault<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+            /** Text patterns to match in alert messages */
+            alertPatterns: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            dialogs: boolean;
+            console: boolean;
+            consoleMarker: string;
+            domMutation: boolean;
+            severity: "critical" | "high" | "medium" | "low";
+            alertPatterns: string[];
+        }, {
+            dialogs?: boolean | undefined;
+            console?: boolean | undefined;
+            consoleMarker?: string | undefined;
+            domMutation?: boolean | undefined;
+            severity?: "critical" | "high" | "medium" | "low" | undefined;
+            alertPatterns?: string[] | undefined;
+        }>>;
+        /** Reflection detection settings */
+        reflection: z.ZodDefault<z.ZodObject<{
+            /** Enable reflection detection */
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            /** Minimum payload length to check */
+            minLength: z.ZodDefault<z.ZodNumber>;
+            /** Which HTML contexts to check for reflections */
+            contexts: z.ZodDefault<z.ZodObject<{
+                script: z.ZodDefault<z.ZodBoolean>;
+                attribute: z.ZodDefault<z.ZodBoolean>;
+                body: z.ZodDefault<z.ZodBoolean>;
+            }, "strip", z.ZodTypeAny, {
+                script: boolean;
+                attribute: boolean;
+                body: boolean;
+            }, {
+                script?: boolean | undefined;
+                attribute?: boolean | undefined;
+                body?: boolean | undefined;
+            }>>;
+            /** Severity per context */
+            severity: z.ZodDefault<z.ZodObject<{
+                script: z.ZodDefault<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+                attribute: z.ZodDefault<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+                body: z.ZodDefault<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+            }, "strip", z.ZodTypeAny, {
+                script: "critical" | "high" | "medium" | "low";
+                attribute: "critical" | "high" | "medium" | "low";
+                body: "critical" | "high" | "medium" | "low";
+            }, {
+                script?: "critical" | "high" | "medium" | "low" | undefined;
+                attribute?: "critical" | "high" | "medium" | "low" | undefined;
+                body?: "critical" | "high" | "medium" | "low" | undefined;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            severity: {
+                script: "critical" | "high" | "medium" | "low";
+                attribute: "critical" | "high" | "medium" | "low";
+                body: "critical" | "high" | "medium" | "low";
+            };
+            enabled: boolean;
+            minLength: number;
+            contexts: {
+                script: boolean;
+                attribute: boolean;
+                body: boolean;
+            };
+        }, {
+            severity?: {
+                script?: "critical" | "high" | "medium" | "low" | undefined;
+                attribute?: "critical" | "high" | "medium" | "low" | undefined;
+                body?: "critical" | "high" | "medium" | "low" | undefined;
+            } | undefined;
+            enabled?: boolean | undefined;
+            minLength?: number | undefined;
+            contexts?: {
+                script?: boolean | undefined;
+                attribute?: boolean | undefined;
+                body?: boolean | undefined;
+            } | undefined;
+        }>>;
+        /** Enable passive security checks (headers, cookies, info-disclosure) */
+        passive: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        xss: {
+            dialogs: boolean;
+            console: boolean;
+            consoleMarker: string;
+            domMutation: boolean;
+            severity: "critical" | "high" | "medium" | "low";
+            alertPatterns: string[];
+        };
+        reflection: {
+            severity: {
+                script: "critical" | "high" | "medium" | "low";
+                attribute: "critical" | "high" | "medium" | "low";
+                body: "critical" | "high" | "medium" | "low";
+            };
+            enabled: boolean;
+            minLength: number;
+            contexts: {
+                script: boolean;
+                attribute: boolean;
+                body: boolean;
+            };
+        };
+        passive: boolean;
+    }, {
+        xss?: {
+            dialogs?: boolean | undefined;
+            console?: boolean | undefined;
+            consoleMarker?: string | undefined;
+            domMutation?: boolean | undefined;
+            severity?: "critical" | "high" | "medium" | "low" | undefined;
+            alertPatterns?: string[] | undefined;
+        } | undefined;
+        reflection?: {
+            severity?: {
+                script?: "critical" | "high" | "medium" | "low" | undefined;
+                attribute?: "critical" | "high" | "medium" | "low" | undefined;
+                body?: "critical" | "high" | "medium" | "low" | undefined;
+            } | undefined;
+            enabled?: boolean | undefined;
+            minLength?: number | undefined;
+            contexts?: {
+                script?: boolean | undefined;
+                attribute?: boolean | undefined;
+                body?: boolean | undefined;
+            } | undefined;
+        } | undefined;
+        passive?: boolean | undefined;
+    }>>;
+    /** Crawl configuration */
+    crawl: z.ZodDefault<z.ZodObject<{
+        /** Maximum crawl depth */
+        depth: z.ZodDefault<z.ZodNumber>;
+        /** Maximum pages to visit */
+        maxPages: z.ZodDefault<z.ZodNumber>;
+        /** Stay on same origin */
+        sameOrigin: z.ZodDefault<z.ZodBoolean>;
+        /** Per-page timeout in ms */
+        timeout: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        timeout: number;
+        depth: number;
+        maxPages: number;
+        sameOrigin: boolean;
+    }, {
+        timeout?: number | undefined;
+        depth?: number | undefined;
+        maxPages?: number | undefined;
+        sameOrigin?: boolean | undefined;
+    }>>;
+    /** Report configuration */
+    report: z.ZodDefault<z.ZodObject<{
+        /** Report format to generate */
+        format: z.ZodDefault<z.ZodNullable<z.ZodEnum<["html", "json", "yaml", "sarif", "all"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        format: "html" | "json" | "yaml" | "sarif" | "all" | null;
+    }, {
+        format?: "html" | "json" | "yaml" | "sarif" | "all" | null | undefined;
+    }>>;
+    /** Authentication configuration */
+    auth: z.ZodDefault<z.ZodNullable<z.ZodDiscriminatedUnion<"strategy", [z.ZodObject<{
+        strategy: z.ZodLiteral<"form">;
+        /** Login page URL */
+        loginUrl: z.ZodOptional<z.ZodString>;
+        /** CSS selector for username field */
+        userSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** CSS selector for password field */
+        passSelector: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "form";
+        userSelector: string | null;
+        passSelector: string | null;
+        loginUrl?: string | undefined;
+    }, {
+        strategy: "form";
+        loginUrl?: string | undefined;
+        userSelector?: string | null | undefined;
+        passSelector?: string | null | undefined;
+    }>, z.ZodObject<{
+        strategy: z.ZodLiteral<"header">;
+        /** Headers to include in requests */
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        strategy: "header";
+        headers: Record<string, string>;
+    }, {
+        strategy: "header";
+        headers: Record<string, string>;
+    }>]>>>;
+}, "strip", z.ZodTypeAny, {
+    scan: {
+        browser: "chromium" | "firefox" | "webkit";
+        headless: boolean;
+        timeout: number;
+    };
+    payloads: {
+        custom: string | null;
+        types: ("xss" | "sqli" | "xxe" | "cmd" | "redirect" | "traversal")[];
+        payloadbox: boolean;
+        limit: number;
+    };
+    detection: {
+        xss: {
+            dialogs: boolean;
+            console: boolean;
+            consoleMarker: string;
+            domMutation: boolean;
+            severity: "critical" | "high" | "medium" | "low";
+            alertPatterns: string[];
+        };
+        reflection: {
+            severity: {
+                script: "critical" | "high" | "medium" | "low";
+                attribute: "critical" | "high" | "medium" | "low";
+                body: "critical" | "high" | "medium" | "low";
+            };
+            enabled: boolean;
+            minLength: number;
+            contexts: {
+                script: boolean;
+                attribute: boolean;
+                body: boolean;
+            };
+        };
+        passive: boolean;
+    };
+    crawl: {
+        timeout: number;
+        depth: number;
+        maxPages: number;
+        sameOrigin: boolean;
+    };
+    report: {
+        format: "html" | "json" | "yaml" | "sarif" | "all" | null;
+    };
+    auth: {
+        strategy: "form";
+        userSelector: string | null;
+        passSelector: string | null;
+        loginUrl?: string | undefined;
+    } | {
+        strategy: "header";
+        headers: Record<string, string>;
+    } | null;
+    target?: string | undefined;
+}, {
+    target?: string | undefined;
+    scan?: {
+        browser?: "chromium" | "firefox" | "webkit" | undefined;
+        headless?: boolean | undefined;
+        timeout?: number | undefined;
+    } | undefined;
+    payloads?: {
+        custom?: string | null | undefined;
+        types?: ("xss" | "sqli" | "xxe" | "cmd" | "redirect" | "traversal")[] | undefined;
+        payloadbox?: boolean | undefined;
+        limit?: number | undefined;
+    } | undefined;
+    detection?: {
+        xss?: {
+            dialogs?: boolean | undefined;
+            console?: boolean | undefined;
+            consoleMarker?: string | undefined;
+            domMutation?: boolean | undefined;
+            severity?: "critical" | "high" | "medium" | "low" | undefined;
+            alertPatterns?: string[] | undefined;
+        } | undefined;
+        reflection?: {
+            severity?: {
+                script?: "critical" | "high" | "medium" | "low" | undefined;
+                attribute?: "critical" | "high" | "medium" | "low" | undefined;
+                body?: "critical" | "high" | "medium" | "low" | undefined;
+            } | undefined;
+            enabled?: boolean | undefined;
+            minLength?: number | undefined;
+            contexts?: {
+                script?: boolean | undefined;
+                attribute?: boolean | undefined;
+                body?: boolean | undefined;
+            } | undefined;
+        } | undefined;
+        passive?: boolean | undefined;
+    } | undefined;
+    crawl?: {
+        timeout?: number | undefined;
+        depth?: number | undefined;
+        maxPages?: number | undefined;
+        sameOrigin?: boolean | undefined;
+    } | undefined;
+    report?: {
+        format?: "html" | "json" | "yaml" | "sarif" | "all" | null | undefined;
+    } | undefined;
+    auth?: {
+        strategy: "form";
+        loginUrl?: string | undefined;
+        userSelector?: string | null | undefined;
+        passSelector?: string | null | undefined;
+    } | {
+        strategy: "header";
+        headers: Record<string, string>;
+    } | null | undefined;
+}>;
+/** Parsed and validated project config */
+type VulcnProjectConfig = z.infer<typeof VulcnProjectConfigSchema>;
+/**
+ * Parse and validate a raw config object (from YAML.parse).
+ * All fields have defaults, so an empty object is valid.
+ */
+declare function parseProjectConfig(raw: unknown): VulcnProjectConfig;
+/**
+ * Default config for `vulcn init`.
+ * Only includes fields that users are likely to customize.
+ */
+declare const DEFAULT_PROJECT_CONFIG: {
+    readonly target: "https://example.com";
+    readonly scan: {
+        readonly browser: "chromium";
+        readonly headless: true;
+        readonly timeout: 30000;
+    };
+    readonly payloads: {
+        readonly types: readonly ["xss"];
+    };
+    readonly detection: {
+        readonly xss: {
+            readonly dialogs: true;
+            readonly console: true;
+            readonly domMutation: false;
+            readonly severity: "high";
+        };
+        readonly reflection: {
+            readonly enabled: true;
+        };
+        readonly passive: true;
+    };
+    readonly crawl: {
+        readonly depth: 2;
+        readonly maxPages: 20;
+        readonly sameOrigin: true;
+    };
+    readonly report: {
+        readonly format: "html";
+    };
+};
+
+/**
+ * Vulcn Project Discovery & Resolution
+ *
+ * Finds `.vulcn.yml` by walking up from `cwd`, parses the config,
+ * and resolves convention-based paths (sessions/, auth/, reports/).
+ */
+
+/** Config filename — presence marks a directory as a Vulcn project */
+declare const CONFIG_FILENAME = ".vulcn.yml";
+/** Convention-based subdirectory names */
+declare const DIRS: {
+    readonly sessions: "sessions";
+    readonly auth: "auth";
+    readonly reports: "reports";
+};
+/** Resolved project paths */
+interface ProjectPaths {
+    /** Absolute path to the project root (directory containing .vulcn.yml) */
+    root: string;
+    /** Absolute path to .vulcn.yml */
+    config: string;
+    /** Absolute path to sessions/ directory */
+    sessions: string;
+    /** Absolute path to auth/ directory */
+    auth: string;
+    /** Absolute path to reports/ directory */
+    reports: string;
+}
+/** Loaded project — config + paths */
+interface VulcnProject {
+    /** Parsed and validated config */
+    config: VulcnProjectConfig;
+    /** Resolved absolute paths */
+    paths: ProjectPaths;
+}
+/**
+ * Find the project root by walking up from `startDir` looking for `.vulcn.yml`.
+ *
+ * @param startDir - Directory to start searching from (default: `cwd()`)
+ * @returns Absolute path to the project root, or `null` if not found
+ */
+declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Resolve convention-based paths from a project root.
+ */
+declare function resolveProjectPaths(root: string): ProjectPaths;
+/**
+ * Load a Vulcn project from a directory.
+ *
+ * Finds `.vulcn.yml`, parses it, validates with Zod, and resolves paths.
+ *
+ * @param startDir - Directory to start searching from (default: `cwd()`)
+ * @throws If `.vulcn.yml` is not found or invalid
+ */
+declare function loadProject(startDir?: string): Promise<VulcnProject>;
+/**
+ * Load project config from a specific file path (no discovery).
+ * Useful for testing or when the path is already known.
+ */
+declare function loadProjectFromFile(configPath: string): Promise<VulcnProject>;
+/**
+ * Ensure convention directories exist (sessions/, auth/, reports/).
+ * Called during init and before operations that write to these dirs.
+ */
+declare function ensureProjectDirs(paths: ProjectPaths, dirs?: Array<keyof typeof DIRS>): Promise<void>;
+
 /**
  * Payload Types for Vulcn
  * Core types used by the engine and plugins
@@ -11,7 +485,7 @@ type PayloadCategory = "xss" | "sqli" | "ssrf" | "xxe" | "command-injection" | "
 /**
  * Payload source types
  */
-type PayloadSource = "custom" | "payloadbox" | "plugin";
+type PayloadSource = "curated" | "custom" | "payloadbox" | "plugin";
 /**
  * Runtime payload structure - used by plugins and the runner
  */
@@ -46,9 +520,18 @@ interface CustomPayloadFile {
     version?: string;
     payloads: CustomPayload[];
 }
+/**
+ * Determine finding severity based on vulnerability category.
+ *
+ * Central mapping used by all drivers and plugins — single source of truth
+ * so severity ratings remain consistent across Tier 1 (HTTP) and Tier 2 (browser) scans.
+ */
+declare function getSeverity(category: PayloadCategory): "critical" | "high" | "medium" | "low" | "info";
 
 interface Finding {
     type: PayloadCategory;
+    /** CWE identifier (e.g., "CWE-79" for XSS, "CWE-89" for SQLi) */
+    cwe?: string;
     severity: "critical" | "high" | "medium" | "low" | "info";
     title: string;
     description: string;
@@ -60,6 +543,111 @@ interface Finding {
     metadata?: Record<string, unknown>;
 }
 
+/**
+ * Vulcn Error System
+ *
+ * Centralized error handling with severity classification.
+ * Components emit errors here instead of making local catch/swallow decisions.
+ *
+ * Severity levels:
+ *   FATAL  — Stop execution immediately. The operation cannot continue.
+ *            Examples: report plugin fails to write, payload loading fails,
+ *            driver can't launch browser.
+ *
+ *   ERROR  — Something broke but execution can continue. Record it.
+ *            Examples: a single session times out, a plugin hook fails
+ *            on a non-critical lifecycle event.
+ *
+ *   WARN   — Expected or recoverable. Log and move on.
+ *            Examples: optional plugin not installed, browser page navigation
+ *            intermittently fails, auth state not found.
+ */
+declare enum ErrorSeverity {
+    /** Stop execution — unrecoverable */
+    FATAL = "fatal",
+    /** Record and continue — something broke but others can proceed */
+    ERROR = "error",
+    /** Log and move on — expected or minor */
+    WARN = "warn"
+}
+declare class VulcnError extends Error {
+    readonly severity: ErrorSeverity;
+    readonly source: string;
+    readonly context?: Record<string, unknown>;
+    readonly timestamp: string;
+    constructor(message: string, options: {
+        severity: ErrorSeverity;
+        source: string;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Wrap any caught error into a VulcnError.
+     * If it's already a VulcnError, returns it as-is.
+     */
+    static from(err: unknown, defaults: {
+        severity: ErrorSeverity;
+        source: string;
+        context?: Record<string, unknown>;
+    }): VulcnError;
+}
+declare function fatal(message: string, source: string, options?: {
+    cause?: unknown;
+    context?: Record<string, unknown>;
+}): VulcnError;
+declare function error(message: string, source: string, options?: {
+    cause?: unknown;
+    context?: Record<string, unknown>;
+}): VulcnError;
+declare function warn(message: string, source: string, options?: {
+    cause?: unknown;
+    context?: Record<string, unknown>;
+}): VulcnError;
+type ErrorListener = (error: VulcnError) => void;
+/**
+ * Central error handler for the Vulcn engine.
+ *
+ * - FATAL errors throw immediately (halt execution)
+ * - ERROR errors are recorded and logged
+ * - WARN errors are logged only
+ *
+ * At the end of a run/scan, call `getSummary()` to see everything that went wrong.
+ */
+declare class ErrorHandler {
+    private errors;
+    private 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: VulcnError): void;
+    /**
+     * Convenience: wrap a caught error and handle it.
+     */
+    catch(err: unknown, defaults: {
+        severity: ErrorSeverity;
+        source: string;
+        context?: Record<string, unknown>;
+    }): void;
+    /** All recorded errors (FATAL + ERROR + WARN) */
+    getAll(): VulcnError[];
+    /** Only ERROR and FATAL */
+    getErrors(): VulcnError[];
+    /** Were there any errors (not just warnings)? */
+    hasErrors(): boolean;
+    /** Count by severity */
+    counts(): Record<ErrorSeverity, number>;
+    /** Human-readable summary for end-of-run reporting */
+    getSummary(): string;
+    /** Subscribe to errors as they happen */
+    onError(listener: ErrorListener): () => void;
+    /** Reset for a new run */
+    clear(): void;
+}
+
 /**
  * Vulcn Plugin System Types
  * @module @vulcn/engine/plugin
@@ -173,7 +761,7 @@ interface EngineInfo {
  * Base context available to all plugin hooks
  */
 interface PluginContext {
-    /** Plugin-specific config from vulcn.config.yml */
+    /** Plugin-specific configuration */
     config: Record<string, unknown>;
     /** Engine information */
     engine: EngineInfo;
@@ -189,6 +777,13 @@ interface PluginContext {
     addFinding: (finding: Finding) => void;
     /** Scoped logger */
     logger: PluginLogger;
+    /**
+     * Centralized error handler.
+     * Plugins MUST use this to surface errors instead of swallowing them:
+     *   ctx.errors.fatal("can't write report", "plugin:report", { cause: err })
+     *   ctx.errors.warn("optional feature unavailable", "plugin:passive")
+     */
+    errors: ErrorHandler;
     /** Fetch API for network requests */
     fetch: typeof fetch;
 }
@@ -234,31 +829,6 @@ interface DetectContext extends RunContext$1 {
     /** Step ID for reporting */
     stepId: string;
 }
-/**
- * Plugin configuration in vulcn.config.yml
- */
-interface PluginConfig {
-    /** Plugin name/path */
-    name: string;
-    /** Plugin-specific configuration */
-    config?: Record<string, unknown>;
-    /** Whether plugin is enabled (default: true) */
-    enabled?: boolean;
-}
-/**
- * Vulcn configuration file schema
- */
-interface VulcnConfig {
-    /** Config version */
-    version: string;
-    /** Plugins to load */
-    plugins?: PluginConfig[];
-    /** Global settings */
-    settings?: {
-        headless?: boolean;
-        timeout?: number;
-    };
-}
 /**
  * Loaded plugin instance with resolved config
  */
@@ -275,7 +845,11 @@ interface LoadedPlugin {
 
 /**
  * Vulcn Plugin Manager
- * Handles plugin loading, lifecycle, and hook execution
+ * Handles plugin loading, lifecycle, and hook execution.
+ *
+ * The primary entry point is `loadFromConfig(config)` which takes
+ * a flat `VulcnProjectConfig` (from `.vulcn.yml`) and maps it to
+ * internal plugin configs automatically.
  */
 
 /**
@@ -283,25 +857,16 @@ interface LoadedPlugin {
  */
 declare class PluginManager {
     private plugins;
-    private config;
     private initialized;
+    private errorHandler;
     /**
      * Shared context passed to all plugins
      */
     private sharedPayloads;
     private sharedFindings;
-    /**
-     * Load configuration from vulcn.config.yml
-     */
-    loadConfig(configPath?: string): Promise<VulcnConfig>;
-    /**
-     * Load all plugins from config
-     */
-    loadPlugins(): Promise<void>;
-    /**
-     * Load a single plugin
-     */
-    private loadPlugin;
+    constructor(errorHandler?: ErrorHandler);
+    /** Get the error handler for post-run inspection */
+    getErrorHandler(): ErrorHandler;
     /**
      * Validate plugin structure
      */
@@ -318,6 +883,15 @@ declare class PluginManager {
      * Destroy all plugins (call onDestroy hooks)
      */
     destroy(): Promise<void>;
+    /**
+     * 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
+     */
+    loadFromConfig(config: VulcnProjectConfig): Promise<void>;
     /**
      * Get all loaded payloads
      */
@@ -349,11 +923,14 @@ declare class PluginManager {
     /**
      * Create base context for plugins
      */
-    createContext(pluginConfig: Record<string, unknown>): PluginContext;
+    createContext(pluginConfig: Record<string, unknown>, pluginName?: string): PluginContext;
     /**
      * Create scoped logger for a plugin
      */
     private createLogger;
+    private static readonly FATAL_HOOKS;
+    private static readonly ERROR_HOOKS;
+    private hookSeverity;
     /**
      * Call a hook on all plugins sequentially
      */
@@ -435,6 +1012,13 @@ interface RunContext {
     addFinding(finding: Finding): void;
     /** Logger */
     logger: DriverLogger;
+    /**
+     * Centralized error handler.
+     * Drivers MUST use this to surface errors:
+     *   ctx.errors.fatal("session data malformed", "driver:browser")
+     *   ctx.errors.warn("page timeout", "driver:browser")
+     */
+    errors: ErrorHandler;
     /** Running options */
     options: RunOptions;
 }
@@ -480,6 +1064,16 @@ interface RunOptions {
     onFinding?: (finding: Finding) => void;
     /** Callback for step completion */
     onStepComplete?: (stepId: string, payloadCount: number) => void;
+    /**
+     * Called by executeScan before each session starts.
+     * Provides the session name, index, and total count for progress tracking.
+     */
+    onSessionStart?: (session: Session, index: number, total: number) => void;
+    /**
+     * Called by executeScan after each session completes.
+     * Provides the result for that session.
+     */
+    onSessionEnd?: (session: Session, result: RunResult, index: number, total: number) => void;
     /**
      * Called by the driver runner after the page/environment is ready.
      * The driver-manager uses this to fire plugin onRunStart hooks
@@ -492,7 +1086,19 @@ interface RunOptions {
      * so plugins can flush pending async work.
      */
     onBeforeClose?: (page: unknown) => Promise<void>;
-    /** Driver-specific options */
+    /**
+     * Per-session timeout in milliseconds.
+     * If a session exceeds this duration, it will be aborted with a timeout error.
+     * Both CLI and Worker benefit from this when using `executeScan`.
+     */
+    timeout?: number;
+    /** Shared browser instance (passed by executeScan for persistent mode) */
+    browser?: unknown;
+    /** JSON-stringified browser storage state (cookies, localStorage) for authenticated scans */
+    storageState?: string;
+    /** Extra HTTP headers to inject into every request (for header-based auth) */
+    extraHeaders?: Record<string, string>;
+    /** Allow additional driver-specific options */
     [key: string]: unknown;
 }
 /**
@@ -580,6 +1186,14 @@ interface VulcnDriver {
     recorder: RecorderDriver;
     /** Runner implementation */
     runner: RunnerDriver;
+    /**
+     * Create a shared resource (e.g., a browser instance) that can be
+     * passed to execute() via ctx.options.
+     *
+     * Used by executeScan() to improve performance by reusing resources
+     * across multiple sessions.
+     */
+    createSharedResource?: (config: Record<string, unknown>, options: RunOptions) => Promise<unknown>;
 }
 /**
  * Driver source for loading
@@ -599,6 +1213,7 @@ interface LoadedDriver {
  * Handles driver loading, registration, and lifecycle.
  * Drivers are loaded from npm packages or local files.
  */
+declare const ENGINE_VERSION: any;
 
 /**
  * Driver Manager - loads and manages recording/running drivers
@@ -641,15 +1256,11 @@ declare class DriverManager {
     /**
      * 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: string, defaultDriver?: string): Session;
+    parseSession(yaml: string): Session;
     /**
      * Start recording with a driver
      */
@@ -796,57 +1407,10 @@ declare function decryptStorageState(encrypted: string, passphrase: string): str
 declare function getPassphrase(interactive?: string): string;
 
 /**
- * Vulcn Session Format v2
+ * Vulcn Session Utilities
  *
- * Directory-based session format: `.vulcn/` or `<name>.vulcn/`
- *
- * Structure:
- *   manifest.yml          - scan config, session list, auth config
- *   auth/config.yml       - login strategy, indicators
- *   auth/state.enc        - encrypted storageState (cookies/localStorage)
- *   sessions/*.yml        - individual session files (one per form)
- *   requests/*.json       - captured HTTP metadata (for Tier 1 fast scan)
+ * Types and utilities used by the driver system for HTTP request metadata.
  */
-
-/** Manifest file schema (manifest.yml) */
-interface ScanManifest {
-    /** Format version */
-    version: "2";
-    /** Human-readable scan name */
-    name: string;
-    /** Target URL */
-    target: string;
-    /** When the scan was recorded */
-    recordedAt: string;
-    /** Driver name */
-    driver: string;
-    /** Driver configuration */
-    driverConfig: Record<string, unknown>;
-    /** Auth configuration (optional) */
-    auth?: {
-        strategy: string;
-        configFile?: string;
-        stateFile?: string;
-        loggedInIndicator?: string;
-        loggedOutIndicator?: string;
-        reAuthOn?: Array<Record<string, unknown>>;
-    };
-    /** Session file references */
-    sessions: SessionRef[];
-    /** Scan configuration */
-    scan?: {
-        tier?: "auto" | "http-only" | "browser-only";
-        parallel?: number;
-        timeout?: number;
-    };
-}
-/** Reference to a session file within the manifest */
-interface SessionRef {
-    /** Relative path to session file */
-    file: string;
-    /** Whether this session has injectable inputs */
-    injectable?: boolean;
-}
 /** HTTP request metadata for Tier 1 fast scanning */
 interface CapturedRequest {
     /** Request method */
@@ -864,54 +1428,5 @@ interface CapturedRequest {
     /** Session name this request belongs to */
     sessionName: string;
 }
-/**
- * Load a v2 session directory into Session[] ready for execution.
- *
- * @param dirPath - Path to the .vulcn/ directory
- * @returns Array of sessions with manifest metadata attached
- */
-declare function loadSessionDir(dirPath: string): Promise<{
-    manifest: ScanManifest;
-    sessions: Session[];
-    authConfig?: AuthConfig;
-}>;
-/**
- * Check if a path is a v2 session directory.
- */
-declare function isSessionDir(path: string): boolean;
-/**
- * Check if a path looks like a v2 session directory (by extension).
- */
-declare function looksLikeSessionDir(path: string): boolean;
-/**
- * Save sessions to a v2 session directory.
- *
- * Creates the directory structure:
- *   <dirPath>/
- *   ├── manifest.yml
- *   ├── sessions/
- *   │   ├── <session-name>.yml
- *   │   └── ...
- *   └── requests/   (if HTTP metadata provided)
- *       └── ...
- */
-declare function saveSessionDir(dirPath: string, options: {
-    name: string;
-    target: string;
-    driver: string;
-    driverConfig: Record<string, unknown>;
-    sessions: Session[];
-    authConfig?: AuthConfig;
-    encryptedState?: string;
-    requests?: CapturedRequest[];
-}): Promise<void>;
-/**
- * Read encrypted auth state from a session directory.
- */
-declare function readAuthState(dirPath: string): Promise<string | null>;
-/**
- * Read captured HTTP requests from a session directory.
- */
-declare function readCapturedRequests(dirPath: string): Promise<CapturedRequest[]>;
 
-export { type AuthConfig, type CapturedRequest, type CrawlOptions, type Credentials, type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, type FormCredentials, type HeaderCredentials, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type RunContext$1 as PluginRunContext, type PluginSource, type RecordContext, type RecordOptions, type RecorderDriver, type RecordingHandle, type RunContext, type RunOptions, type RunResult, type RunnerDriver, type RuntimePayload, type ScanContext, type ScanManifest, type Session, type SessionRef, type Step, type VulcnConfig, type VulcnDriver, type VulcnPlugin, decrypt, decryptCredentials, decryptStorageState, driverManager, encrypt, encryptCredentials, encryptStorageState, getPassphrase, isSessionDir, loadSessionDir, looksLikeSessionDir, pluginManager, readAuthState, readCapturedRequests, saveSessionDir };
+export { type AuthConfig, CONFIG_FILENAME, type CapturedRequest, type CrawlOptions, type Credentials, type CustomPayload, type CustomPayloadFile, DEFAULT_PROJECT_CONFIG, DIRS, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, ENGINE_VERSION, type EngineInfo, ErrorHandler, type ErrorListener, ErrorSeverity, type Finding, type FormCredentials, type HeaderCredentials, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type RunContext$1 as PluginRunContext, type PluginSource, type ProjectPaths, type RecordContext, type RecordOptions, type RecorderDriver, type RecordingHandle, type RunContext, type RunOptions, type RunResult, type RunnerDriver, type RuntimePayload, type ScanContext, type Session, type Step, type VulcnDriver, VulcnError, type VulcnPlugin, type VulcnProject, type VulcnProjectConfig, VulcnProjectConfigSchema, decrypt, decryptCredentials, decryptStorageState, driverManager, encrypt, encryptCredentials, encryptStorageState, ensureProjectDirs, error, fatal, findProjectRoot, getPassphrase, getSeverity, loadProject, loadProjectFromFile, parseProjectConfig, pluginManager, resolveProjectPaths, warn };