@vulcn/driver-browser 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, VulcnDriver } from '@vulcn/engine';
-import { Browser } from 'playwright';
+import { RecordOptions, RecordingHandle, Session, RunContext, RunResult, CrawlOptions, FormCredentials, VulcnDriver } from '@vulcn/engine';
+import { Browser, Page, BrowserContext } from 'playwright';
 
 /**
  * Browser Recorder Implementation
@@ -32,33 +32,31 @@ declare class BrowserRecorder {
  *
  * Replays browser sessions with security payloads.
  * Uses plugin hooks for detection.
+ *
+ * v2: Persistent browser with in-page payload cycling.
+ *   - ONE browser for the entire scan (not per-session)
+ *   - Uses page.goBack() between payloads instead of full page.goto()
+ *   - Falls back to full navigation when goBack() fails
+ *   - 5-10x faster on SPAs, same speed on simple sites
  */
 
 /**
  * Browser Runner - replays sessions with payloads
+ *
+ * Supports two modes:
+ * 1. Self-managed browser: launches its own browser (backward compat)
+ * 2. Shared browser: receives a browser instance via RunOptions
+ *
+ * In both modes, payload cycling uses goBack() for speed.
  */
 declare class BrowserRunner {
     /**
-     * Execute a session with security payloads
-     */
-    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
-    /**
-     * Replay session steps with payload injected at target step
+     * Execute a session with security payloads.
      *
-     * IMPORTANT: We replay ALL steps, not just up to the injectable step.
-     * The injection replaces the input value, but subsequent steps (like
-     * clicking submit) must still execute so the payload reaches the server
-     * and gets reflected back in the response.
-     */
-    private static replayWithPayload;
-    /**
-     * Check for payload reflection in page content
+     * If ctx.options.browser is provided, reuses that browser (persistent mode).
+     * Otherwise, launches and closes its own browser (standalone mode).
      */
-    private static checkReflection;
-    /**
-     * Determine severity based on vulnerability category
-     */
-    private static getSeverity;
+    static execute(session: Session, ctx: RunContext): Promise<RunResult>;
 }
 
 /**
@@ -130,6 +128,77 @@ interface BrowserCrawlConfig {
  */
 declare function crawlAndBuildSessions(config: BrowserCrawlConfig, options?: CrawlOptions): Promise<Session[]>;
 
+/**
+ * Login Form Auto-Detection & Auth Replay
+ *
+ * Detects login forms on a page and fills them with credentials.
+ * After login, captures the browser storage state (cookies + localStorage)
+ * for re-use in subsequent scans.
+ *
+ * Detection strategy:
+ * 1. Find forms with a password input (strongest signal)
+ * 2. Find username field via heuristics (name, id, autocomplete, type)
+ * 3. Find submit button
+ * 4. Fall back to custom selectors from credentials
+ */
+
+interface LoginForm {
+    /** Username input selector */
+    usernameSelector: string;
+    /** Password input selector */
+    passwordSelector: string;
+    /** Submit button selector (may be null if not found) */
+    submitSelector: string | null;
+    /** Whether the form was detected automatically */
+    autoDetected: boolean;
+}
+interface LoginResult {
+    /** Whether login succeeded */
+    success: boolean;
+    /** Message for logging */
+    message: string;
+    /** Playwright storage state JSON (cookies + localStorage) */
+    storageState?: string;
+}
+/**
+ * Auto-detect a login form on the current page.
+ *
+ * Strategy:
+ * 1. Find `<form>` elements containing an `input[type="password"]`
+ * 2. Within that form, find the username field using heuristics
+ * 3. Find the submit button
+ *
+ * Falls back to page-wide search if no enclosing <form> is found.
+ */
+declare function detectLoginForm(page: Page): Promise<LoginForm | null>;
+/**
+ * Perform login using detected form or custom selectors.
+ *
+ * Flow:
+ * 1. Navigate to login URL (or target URL)
+ * 2. Detect login form (or use custom selectors from credentials)
+ * 3. Fill username + password
+ * 4. Submit form
+ * 5. Wait for navigation
+ * 6. Check for logged-in indicator
+ * 7. Capture storage state
+ */
+declare function performLogin(page: Page, context: BrowserContext, credentials: FormCredentials, options: {
+    targetUrl: string;
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<LoginResult>;
+/**
+ * Check if the current session is still alive.
+ *
+ * Used during long-running scans to detect session expiry
+ * and trigger re-authentication.
+ */
+declare function checkSessionAlive(page: Page, config: {
+    loggedInIndicator?: string;
+    loggedOutIndicator?: string;
+}): Promise<boolean>;
+
 /**
  * @vulcn/driver-browser
  *
@@ -334,4 +403,4 @@ type BrowserStep = z.infer<typeof BrowserStepSchema>;
  */
 declare const browserDriver: VulcnDriver;
 
-export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, checkBrowsers, configSchema, crawlAndBuildSessions, browserDriver as default, installBrowsers, launchBrowser };
+export { BROWSER_STEP_TYPES, type BrowserConfig, BrowserRecorder, BrowserRunner, type BrowserStep, BrowserStepSchema, type BrowserStepType, type LoginForm, type LoginResult, checkBrowsers, checkSessionAlive, configSchema, crawlAndBuildSessions, browserDriver as default, detectLoginForm, installBrowsers, launchBrowser, performLogin };