@vulcn/engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,546 @@
+import { Page, Browser } from 'playwright';
+import { z } from 'zod';
+
+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 = 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 = 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;
+/**
+ * Parse a session from YAML string
+ */
+declare function parseSession(yaml: string): Session;
+/**
+ * Serialize a session to YAML string
+ */
+declare function serializeSession(session: Session): string;
+
+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: "xss" | "sqli" | "ssrf" | "path-traversal" | "custom";
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    title: string;
+    description: string;
+    stepId: string;
+    payload: string;
+    url: string;
+    evidence?: string;
+}
+interface RunResult {
+    findings: Finding[];
+    stepsExecuted: number;
+    payloadsTested: number;
+    duration: number;
+    errors: string[];
+}
+
+/**
+ * Active recording session handle
+ */
+interface RecordingSession {
+    /** Stop recording and return the session */
+    stop(): Promise<Session>;
+    /** Get current recorded steps */
+    getSteps(): Step[];
+    /** Get the Playwright page (for advanced use) */
+    getPage(): Page;
+}
+/**
+ * Recorder - captures browser interactions as a replayable 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): Promise<RecordingSession>;
+    private static attachListeners;
+    private static injectRecordingScript;
+}
+
+/**
+ * Built-in security payloads
+ */
+type PayloadCategory = "xss" | "sqli" | "ssrf" | "path-traversal";
+type PayloadName = "xss-basic" | "xss-event" | "xss-svg" | "sqli-basic" | "sqli-error" | "sqli-blind";
+interface Payload {
+    name: PayloadName;
+    category: PayloadCategory;
+    payloads: string[];
+    detectPatterns: RegExp[];
+    description: string;
+}
+declare const BUILTIN_PAYLOADS: Record<PayloadName, Payload>;
+/**
+ * Get payloads by name
+ */
+declare function getPayload(name: PayloadName): Payload | undefined;
+/**
+ * Get all payload names
+ */
+declare function getPayloadNames(): PayloadName[];
+/**
+ * Get payloads by category
+ */
+declare function getPayloadsByCategory(category: PayloadCategory): Payload[];
+
+/**
+ * Runner - replays sessions with security payloads
+ */
+declare class Runner {
+    /**
+     * Execute a session with security payloads
+     */
+    static execute(session: Session, payloadNames: PayloadName[], options?: RunnerOptions): Promise<RunResult>;
+    private static replayWithPayload;
+    private static checkForVulnerability;
+}
+
+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 { BUILTIN_PAYLOADS, type BrowserLaunchResult, BrowserNotFoundError, type BrowserType, type Finding, type LaunchOptions, type Payload, type PayloadCategory, type PayloadName, Recorder, type RecorderOptions, type RecordingSession, type RunResult, Runner, type RunnerOptions, type Session, SessionSchema, type Step, StepSchema, checkBrowsers, createSession, getPayload, getPayloadNames, getPayloadsByCategory, installBrowsers, launchBrowser, parseSession, serializeSession };