@vulcn/engine 0.3.0 → 0.3.1

package/dist/index.d.cts

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { Page, Dialog, ConsoleMessage, Request, Response, Browser } from 'playwright';
 
 /**
  * Payload Types for Vulcn
@@ -48,20 +47,6 @@ interface CustomPayloadFile {
     payloads: CustomPayload[];
 }
 
-type BrowserType = "chromium" | "firefox" | "webkit";
-interface RecorderOptions {
-    browser?: BrowserType;
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    headless?: boolean;
-}
-interface RunnerOptions {
-    browser?: BrowserType;
-    headless?: boolean;
-    onFinding?: (finding: Finding) => void;
-}
 interface Finding {
     type: PayloadCategory;
     severity: "critical" | "high" | "medium" | "low" | "info";
@@ -74,433 +59,14 @@ interface Finding {
     /** Plugin-specific metadata */
     metadata?: Record<string, unknown>;
 }
-interface RunResult$1 {
-    findings: Finding[];
-    stepsExecuted: number;
-    payloadsTested: number;
-    duration: number;
-    errors: string[];
-}
-
-declare const StepSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"navigate">;
-    url: z.ZodString;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "navigate";
-    id: string;
-    url: string;
-    timestamp: number;
-}, {
-    type: "navigate";
-    id: string;
-    url: string;
-    timestamp: number;
-}>, z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"click">;
-    selector: z.ZodString;
-    position: z.ZodOptional<z.ZodObject<{
-        x: z.ZodNumber;
-        y: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        x: number;
-        y: number;
-    }, {
-        x: number;
-        y: number;
-    }>>;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "click";
-    id: string;
-    timestamp: number;
-    selector: string;
-    position?: {
-        x: number;
-        y: number;
-    } | undefined;
-}, {
-    type: "click";
-    id: string;
-    timestamp: number;
-    selector: string;
-    position?: {
-        x: number;
-        y: number;
-    } | undefined;
-}>, z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"input">;
-    selector: z.ZodString;
-    value: z.ZodString;
-    injectable: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "input";
-    value: string;
-    id: string;
-    timestamp: number;
-    selector: string;
-    injectable: boolean;
-}, {
-    type: "input";
-    value: string;
-    id: string;
-    timestamp: number;
-    selector: string;
-    injectable?: boolean | undefined;
-}>, z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"keypress">;
-    key: z.ZodString;
-    modifiers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "keypress";
-    id: string;
-    timestamp: number;
-    key: string;
-    modifiers?: string[] | undefined;
-}, {
-    type: "keypress";
-    id: string;
-    timestamp: number;
-    key: string;
-    modifiers?: string[] | undefined;
-}>, z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"scroll">;
-    selector: z.ZodOptional<z.ZodString>;
-    position: z.ZodObject<{
-        x: z.ZodNumber;
-        y: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        x: number;
-        y: number;
-    }, {
-        x: number;
-        y: number;
-    }>;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "scroll";
-    id: string;
-    timestamp: number;
-    position: {
-        x: number;
-        y: number;
-    };
-    selector?: string | undefined;
-}, {
-    type: "scroll";
-    id: string;
-    timestamp: number;
-    position: {
-        x: number;
-        y: number;
-    };
-    selector?: string | undefined;
-}>, z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodLiteral<"wait">;
-    duration: z.ZodNumber;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    type: "wait";
-    id: string;
-    timestamp: number;
-    duration: number;
-}, {
-    type: "wait";
-    id: string;
-    timestamp: number;
-    duration: number;
-}>]>;
-type Step$1 = z.infer<typeof StepSchema>;
-declare const SessionSchema: z.ZodObject<{
-    version: z.ZodDefault<z.ZodString>;
-    name: z.ZodString;
-    recordedAt: z.ZodString;
-    browser: z.ZodDefault<z.ZodEnum<["chromium", "firefox", "webkit"]>>;
-    viewport: z.ZodObject<{
-        width: z.ZodNumber;
-        height: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        width: number;
-        height: number;
-    }, {
-        width: number;
-        height: number;
-    }>;
-    startUrl: z.ZodString;
-    steps: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"navigate">;
-        url: z.ZodString;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "navigate";
-        id: string;
-        url: string;
-        timestamp: number;
-    }, {
-        type: "navigate";
-        id: string;
-        url: string;
-        timestamp: number;
-    }>, z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"click">;
-        selector: z.ZodString;
-        position: z.ZodOptional<z.ZodObject<{
-            x: z.ZodNumber;
-            y: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
-            x: number;
-            y: number;
-        }, {
-            x: number;
-            y: number;
-        }>>;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "click";
-        id: string;
-        timestamp: number;
-        selector: string;
-        position?: {
-            x: number;
-            y: number;
-        } | undefined;
-    }, {
-        type: "click";
-        id: string;
-        timestamp: number;
-        selector: string;
-        position?: {
-            x: number;
-            y: number;
-        } | undefined;
-    }>, z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"input">;
-        selector: z.ZodString;
-        value: z.ZodString;
-        injectable: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "input";
-        value: string;
-        id: string;
-        timestamp: number;
-        selector: string;
-        injectable: boolean;
-    }, {
-        type: "input";
-        value: string;
-        id: string;
-        timestamp: number;
-        selector: string;
-        injectable?: boolean | undefined;
-    }>, z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"keypress">;
-        key: z.ZodString;
-        modifiers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "keypress";
-        id: string;
-        timestamp: number;
-        key: string;
-        modifiers?: string[] | undefined;
-    }, {
-        type: "keypress";
-        id: string;
-        timestamp: number;
-        key: string;
-        modifiers?: string[] | undefined;
-    }>, z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"scroll">;
-        selector: z.ZodOptional<z.ZodString>;
-        position: z.ZodObject<{
-            x: z.ZodNumber;
-            y: z.ZodNumber;
-        }, "strip", z.ZodTypeAny, {
-            x: number;
-            y: number;
-        }, {
-            x: number;
-            y: number;
-        }>;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "scroll";
-        id: string;
-        timestamp: number;
-        position: {
-            x: number;
-            y: number;
-        };
-        selector?: string | undefined;
-    }, {
-        type: "scroll";
-        id: string;
-        timestamp: number;
-        position: {
-            x: number;
-            y: number;
-        };
-        selector?: string | undefined;
-    }>, z.ZodObject<{
-        id: z.ZodString;
-        type: z.ZodLiteral<"wait">;
-        duration: z.ZodNumber;
-        timestamp: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        type: "wait";
-        id: string;
-        timestamp: number;
-        duration: number;
-    }, {
-        type: "wait";
-        id: string;
-        timestamp: number;
-        duration: number;
-    }>]>, "many">;
-}, "strip", z.ZodTypeAny, {
-    version: string;
-    name: string;
-    recordedAt: string;
-    browser: "chromium" | "firefox" | "webkit";
-    viewport: {
-        width: number;
-        height: number;
-    };
-    startUrl: string;
-    steps: ({
-        type: "navigate";
-        id: string;
-        url: string;
-        timestamp: number;
-    } | {
-        type: "click";
-        id: string;
-        timestamp: number;
-        selector: string;
-        position?: {
-            x: number;
-            y: number;
-        } | undefined;
-    } | {
-        type: "input";
-        value: string;
-        id: string;
-        timestamp: number;
-        selector: string;
-        injectable: boolean;
-    } | {
-        type: "keypress";
-        id: string;
-        timestamp: number;
-        key: string;
-        modifiers?: string[] | undefined;
-    } | {
-        type: "scroll";
-        id: string;
-        timestamp: number;
-        position: {
-            x: number;
-            y: number;
-        };
-        selector?: string | undefined;
-    } | {
-        type: "wait";
-        id: string;
-        timestamp: number;
-        duration: number;
-    })[];
-}, {
-    name: string;
-    recordedAt: string;
-    viewport: {
-        width: number;
-        height: number;
-    };
-    startUrl: string;
-    steps: ({
-        type: "navigate";
-        id: string;
-        url: string;
-        timestamp: number;
-    } | {
-        type: "click";
-        id: string;
-        timestamp: number;
-        selector: string;
-        position?: {
-            x: number;
-            y: number;
-        } | undefined;
-    } | {
-        type: "input";
-        value: string;
-        id: string;
-        timestamp: number;
-        selector: string;
-        injectable?: boolean | undefined;
-    } | {
-        type: "keypress";
-        id: string;
-        timestamp: number;
-        key: string;
-        modifiers?: string[] | undefined;
-    } | {
-        type: "scroll";
-        id: string;
-        timestamp: number;
-        position: {
-            x: number;
-            y: number;
-        };
-        selector?: string | undefined;
-    } | {
-        type: "wait";
-        id: string;
-        timestamp: number;
-        duration: number;
-    })[];
-    version?: string | undefined;
-    browser?: "chromium" | "firefox" | "webkit" | undefined;
-}>;
-type Session$1 = z.infer<typeof SessionSchema>;
-/**
- * Create a new session object
- */
-declare function createSession(options: {
-    name: string;
-    startUrl: string;
-    browser?: "chromium" | "firefox" | "webkit";
-    viewport?: {
-        width: number;
-        height: number;
-    };
-}): Session$1;
-/**
- * Parse a session from YAML string
- */
-declare function parseSession(yaml: string): Session$1;
-/**
- * Serialize a session to YAML string
- */
-declare function serializeSession(session: Session$1): string;
 
 /**
  * Vulcn Plugin System Types
  * @module @vulcn/engine/plugin
+ *
+ * The plugin system is driver-agnostic. Detection plugins receive
+ * a generic page interface rather than Playwright types directly.
+ * This allows the same plugin to work across different driver types.
  */
 
 /**
@@ -537,6 +103,10 @@ interface VulcnPlugin {
 }
 /**
  * Plugin lifecycle hooks
+ *
+ * Detection hooks (onDialog, onConsoleMessage, etc.) receive
+ * Playwright types from the driver. Plugins that use these
+ * should declare playwright as a peer/dev dependency.
  */
 interface PluginHooks {
     /**
@@ -551,27 +121,27 @@ interface PluginHooks {
     /** Called when recording starts */
     onRecordStart?: (ctx: RecordContext) => Promise<void>;
     /** Called for each recorded step, can transform */
-    onRecordStep?: (step: Step$1, ctx: RecordContext) => Promise<Step$1>;
+    onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
     /** Called when recording ends, can transform session */
-    onRecordEnd?: (session: Session$1, ctx: RecordContext) => Promise<Session$1>;
+    onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
     /** Called when run starts */
     onRunStart?: (ctx: RunContext$1) => Promise<void>;
     /** Called before each payload is injected, can transform payload */
-    onBeforePayload?: (payload: string, step: Step$1, ctx: RunContext$1) => Promise<string>;
+    onBeforePayload?: (payload: string, step: Step, ctx: RunContext$1) => Promise<string>;
     /** Called after payload injection, for detection */
     onAfterPayload?: (ctx: DetectContext) => Promise<Finding[]>;
     /** Called when run ends, can transform results */
-    onRunEnd?: (result: RunResult$1, ctx: RunContext$1) => Promise<RunResult$1>;
-    /** Called on page load/navigation */
-    onPageLoad?: (page: Page, ctx: DetectContext) => Promise<Finding[]>;
+    onRunEnd?: (result: RunResult, ctx: RunContext$1) => Promise<RunResult>;
     /** Called when JavaScript alert/confirm/prompt appears */
-    onDialog?: (dialog: Dialog, ctx: DetectContext) => Promise<Finding | null>;
+    onDialog?: (dialog: unknown, ctx: DetectContext) => Promise<Finding | null>;
     /** Called on console.log/warn/error */
-    onConsoleMessage?: (msg: ConsoleMessage, ctx: DetectContext) => Promise<Finding | null>;
+    onConsoleMessage?: (msg: unknown, ctx: DetectContext) => Promise<Finding | null>;
+    /** Called on page load/navigation */
+    onPageLoad?: (page: unknown, ctx: DetectContext) => Promise<Finding[]>;
     /** Called on network request */
-    onNetworkRequest?: (request: Request, ctx: DetectContext) => Promise<Finding | null>;
+    onNetworkRequest?: (request: unknown, ctx: DetectContext) => Promise<Finding | null>;
     /** Called on network response */
-    onNetworkResponse?: (response: Response, ctx: DetectContext) => Promise<Finding | null>;
+    onNetworkResponse?: (response: unknown, ctx: DetectContext) => Promise<Finding | null>;
 }
 /**
  * Logger interface for plugins
@@ -610,23 +180,17 @@ interface PluginContext {
  * Context for recording phase hooks
  */
 interface RecordContext extends PluginContext {
-    /** Starting URL */
-    startUrl: string;
-    /** Browser type being used */
-    browser: BrowserType;
-    /** Playwright page instance */
-    page: Page;
+    /** Page interface (driver-specific, e.g. Playwright Page) */
+    page: unknown;
 }
 /**
  * Context for running phase hooks
  */
 interface RunContext$1 extends PluginContext {
     /** Session being executed */
-    session: Session$1;
-    /** Playwright page instance */
-    page: Page;
-    /** Browser type being used */
-    browser: BrowserType;
+    session: Session;
+    /** Page interface (driver-specific, e.g. Playwright Page) */
+    page: unknown;
     /** Whether running headless */
     headless: boolean;
 }
@@ -635,7 +199,7 @@ interface RunContext$1 extends PluginContext {
  */
 interface DetectContext extends RunContext$1 {
     /** Current step being tested */
-    step: Step$1;
+    step: Step;
     /** Current payload set being tested */
     payloadSet: RuntimePayload;
     /** Actual payload value injected */
@@ -664,7 +228,6 @@ interface VulcnConfig {
     plugins?: PluginConfig[];
     /** Global settings */
     settings?: {
-        browser?: BrowserType;
         headless?: boolean;
         timeout?: number;
     };
@@ -1001,12 +564,25 @@ declare class DriverManager {
      * Get driver for a session
      */
     getForSession(session: Session): VulcnDriver;
+    /**
+     * 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").
+     *
+     * @param yaml - Raw YAML string
+     * @param defaultDriver - Driver to assign for legacy sessions (default: "browser")
+     */
+    parseSession(yaml: string, defaultDriver?: string): Session;
     /**
      * Start recording with a driver
      */
     startRecording(driverName: string, config: Record<string, unknown>, options?: RecordOptions): Promise<RecordingHandle>;
     /**
      * Execute a session
+     * Invokes plugin hooks (onRunStart, onRunEnd) around the driver runner.
      */
     execute(session: Session, pluginManager: PluginManager, options?: RunOptions): Promise<RunResult>;
     /**
@@ -1023,127 +599,4 @@ declare class DriverManager {
  */
 declare const driverManager: DriverManager;
 
-/**
- * Recorder - captures browser interactions as a replayable session
- * v0.2.0: Plugin hooks for recording customization
- */
-
-/**
- * Configuration for the recorder
- */
-interface RecorderConfig {
-    /** Plugin manager to use (defaults to shared instance) */
-    pluginManager?: PluginManager;
-}
-/**
- * Active recording session handle
- */
-interface RecordingSession {
-    /** Stop recording and return the session */
-    stop(): Promise<Session$1>;
-    /** Get current recorded steps */
-    getSteps(): Step$1[];
-    /** Get the Playwright page (for advanced use) */
-    getPage(): Page;
-}
-/**
- * Recorder - captures browser interactions as a replayable session
- *
- * Uses plugin hooks for:
- * - onRecordStart: Called when recording starts
- * - onRecordStep: Called for each step, can transform
- * - onRecordEnd: Called when recording ends, can transform session
- */
-declare class Recorder {
-    /**
-     * Start a new recording session
-     * Opens a browser window for the user to interact with
-     */
-    static start(startUrl: string, options?: RecorderOptions, config?: RecorderConfig): Promise<RecordingSession>;
-    /**
-     * Transform a step through plugin hooks
-     * Returns null if the step should be filtered out
-     */
-    private static transformStep;
-    private static attachListeners;
-    private static injectRecordingScript;
-}
-
-/**
- * Runner - replays sessions with security payloads
- * v0.2.0: Plugin-based architecture for extensibility
- */
-
-interface RunnerConfig {
-    /** Plugin manager to use (defaults to shared instance) */
-    pluginManager?: PluginManager;
-}
-/**
- * Runner - replays sessions with security payloads
- *
- * Uses plugin hooks for:
- * - Payload loading (onInit)
- * - Payload transformation (onBeforePayload)
- * - Vulnerability detection (onAfterPayload, onDialog, onConsoleMessage, etc.)
- * - Results processing (onRunEnd)
- */
-declare class Runner {
-    /**
-     * Execute a session with security payloads from plugins
-     *
-     * @param session - The recorded session to replay
-     * @param options - Runner configuration
-     * @param config - Plugin manager configuration
-     */
-    static execute(session: Session$1, options?: RunnerOptions, config?: RunnerConfig): Promise<RunResult$1>;
-    /**
-     * Execute with explicit payloads (legacy API, for backwards compatibility)
-     */
-    static executeWithPayloads(session: Session$1, payloads: RuntimePayload[], options?: RunnerOptions): Promise<RunResult$1>;
-    /**
-     * Replay session steps with payload injected at target step
-     */
-    private static replayWithPayload;
-    /**
-     * Basic reflection check - fallback when no detection plugin is loaded
-     */
-    private static checkReflection;
-    /**
-     * Determine severity based on vulnerability category
-     */
-    private static getSeverity;
-}
-
-interface LaunchOptions {
-    browser?: BrowserType;
-    headless?: boolean;
-}
-interface BrowserLaunchResult {
-    browser: Browser;
-    channel?: string;
-}
-declare class BrowserNotFoundError extends Error {
-    constructor(message: string);
-}
-/**
- * Launch a browser with smart fallback:
- * 1. Try system Chrome/Edge first (zero-install experience)
- * 2. Fall back to Playwright's bundled browsers
- */
-declare function launchBrowser(options?: LaunchOptions): Promise<BrowserLaunchResult>;
-/**
- * Install Playwright browsers
- */
-declare function installBrowsers(browsers?: BrowserType[]): Promise<void>;
-/**
- * Check which browsers are available
- */
-declare function checkBrowsers(): Promise<{
-    systemChrome: boolean;
-    systemEdge: boolean;
-    playwrightChromium: boolean;
-    playwrightFirefox: boolean;
-    playwrightWebkit: boolean;
-}>;
-
-export { type BrowserLaunchResult, BrowserNotFoundError, type BrowserType, type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, type LaunchOptions, type Session$1 as LegacySession, type Step$1 as LegacyStep, type LoadedDriver, type LoadedPlugin as LoadedPluginInfo, PLUGIN_API_VERSION, type PayloadCategory, type PayloadSource, type PluginConfig, type PluginContext, type PluginHooks, type PluginLogger, PluginManager, type PluginSource, type RecordContext, type RecordOptions, Recorder, type RecorderDriver, type RecorderOptions, type RecordingHandle, type RecordingSession, type RunContext, type RunOptions, type RunResult, Runner, type RunnerDriver, type RunnerOptions, type RuntimePayload, type Session, SessionSchema, type Step, StepSchema, type VulcnConfig, type VulcnDriver, type VulcnPlugin, checkBrowsers, createSession, driverManager, installBrowsers, launchBrowser, parseSession, pluginManager, serializeSession };
+export { type CustomPayload, type CustomPayloadFile, DRIVER_API_VERSION, type DetectContext, type DriverLogger, DriverManager, type DriverSource, type EngineInfo, type Finding, 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 Session, type Step, type VulcnConfig, type VulcnDriver, type VulcnPlugin, driverManager, pluginManager };