@vulcn/engine 0.5.0 → 0.8.0

package/dist/index.d.cts

@@ -124,12 +124,22 @@ interface PluginHooks {
     onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
     /** Called when recording ends, can transform session */
     onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
+    /** Called once when a scan starts (before any session is executed) */
+    onScanStart?: (ctx: ScanContext) => Promise<void>;
+    /** Called once when a scan ends (after all sessions have executed) */
+    onScanEnd?: (result: RunResult, ctx: ScanContext) => Promise<RunResult>;
     /** Called when run starts */
     onRunStart?: (ctx: RunContext$1) => Promise<void>;
     /** Called before each payload is injected, can transform payload */
     onBeforePayload?: (payload: string, step: Step, ctx: RunContext$1) => Promise<string>;
     /** Called after payload injection, for detection */
     onAfterPayload?: (ctx: DetectContext) => Promise<Finding[]>;
+    /**
+     * Called before the browser/driver is closed.
+     * Plugins should await any pending async work here (e.g., flush
+     * in-flight response handlers that need browser access).
+     */
+    onBeforeClose?: (ctx: PluginContext) => Promise<void>;
     /** Called when run ends, can transform results */
     onRunEnd?: (result: RunResult, ctx: RunContext$1) => Promise<RunResult>;
     /** Called when JavaScript alert/confirm/prompt appears */
@@ -169,8 +179,14 @@ interface PluginContext {
     engine: EngineInfo;
     /** Shared payload registry - loaders add payloads here */
     payloads: RuntimePayload[];
-    /** Shared findings collection - detectors add findings here */
+    /** Shared findings collection (read-only view, use addFinding to add) */
     findings: Finding[];
+    /**
+     * Add a finding through the proper callback chain.
+     * Plugins should use this instead of pushing to findings[] directly,
+     * so consumers (CLI, worker) get notified via onFinding callbacks.
+     */
+    addFinding: (finding: Finding) => void;
     /** Scoped logger */
     logger: PluginLogger;
     /** Fetch API for network requests */
@@ -194,6 +210,17 @@ interface RunContext$1 extends PluginContext {
     /** Whether running headless */
     headless: boolean;
 }
+/**
+ * Context for scan-level hooks (wraps all sessions)
+ */
+interface ScanContext extends PluginContext {
+    /** All sessions in this scan */
+    sessions: Session[];
+    /** Whether running headless */
+    headless: boolean;
+    /** Total sessions count */
+    sessionCount: number;
+}
 /**
  * Context for detection hooks
  */
@@ -438,6 +465,8 @@ interface CrawlOptions {
     pageTimeout?: number;
     /** Only crawl pages under the same origin (default: true) */
     sameOrigin?: boolean;
+    /** Playwright storage state JSON for authenticated crawling */
+    storageState?: string;
     /** Callback when a page is crawled */
     onPageCrawled?: (url: string, formsFound: number) => void;
 }
@@ -451,6 +480,18 @@ interface RunOptions {
     onFinding?: (finding: Finding) => void;
     /** Callback for step completion */
     onStepComplete?: (stepId: string, payloadCount: number) => void;
+    /**
+     * Called by the driver runner after the page/environment is ready.
+     * The driver-manager uses this to fire plugin onRunStart hooks
+     * with the real page object (instead of null).
+     */
+    onPageReady?: (page: unknown) => Promise<void>;
+    /**
+     * Called by the driver runner before closing the browser/environment.
+     * The driver-manager uses this to fire plugin onBeforeClose hooks
+     * so plugins can flush pending async work.
+     */
+    onBeforeClose?: (page: unknown) => Promise<void>;
     /** Driver-specific options */
     [key: string]: unknown;
 }
@@ -627,8 +668,27 @@ declare class DriverManager {
     /**
      * Execute a session
      * Invokes plugin hooks (onRunStart, onRunEnd) around the driver runner.
+     * Plugin onRunStart is deferred until the driver signals the page is ready
+     * via the onPageReady callback, ensuring plugins get a real page object.
      */
     execute(session: Session, pluginManager: PluginManager, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Execute multiple sessions with a shared browser (scan-level orchestration).
+     *
+     * This is the preferred entry point for running a full scan. It:
+     * 1. Launches ONE browser for the entire scan
+     * 2. Passes the browser to each session's runner via options.browser
+     * 3. Each session creates its own context (lightweight, isolated cookies)
+     * 4. Aggregates results across all sessions
+     * 5. Closes the browser once at the end
+     *
+     * This is 5-10x faster than calling execute() per session because
+     * launching a browser takes 2-3 seconds.
+     */
+    executeScan(sessions: Session[], pluginManager: PluginManager, options?: RunOptions): Promise<{
+        results: RunResult[];
+        aggregate: RunResult;
+    }>;
     /**
      * Validate driver structure
      */
@@ -643,4 +703,215 @@ declare class DriverManager {
  */
 declare const driverManager: DriverManager;
 
-export { type CrawlOptions, 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 };
+/**
+ * Vulcn Auth Module
+ *
+ * Handles credential encryption/decryption and auth state management.
+ *
+ * Security:
+ * - AES-256-GCM encryption for credentials at rest
+ * - PBKDF2 key derivation from passphrase
+ * - Reads passphrase from VULCN_KEY env var (CI/CD) or interactive prompt
+ * - Auth state (cookies, localStorage) encrypted separately
+ */
+/** Form-based login credentials */
+interface FormCredentials {
+    type: "form";
+    username: string;
+    password: string;
+    /** Custom login URL (if different from target) */
+    loginUrl?: string;
+    /** Custom CSS selector for username field */
+    userSelector?: string;
+    /** Custom CSS selector for password field */
+    passSelector?: string;
+}
+/** Header-based authentication (API keys, Bearer tokens) */
+interface HeaderCredentials {
+    type: "header";
+    headers: Record<string, string>;
+}
+/** All credential types */
+type Credentials = FormCredentials | HeaderCredentials;
+/** Auth configuration for a scan */
+interface AuthConfig {
+    /** Auth strategy */
+    strategy: "storage-state" | "header";
+    /** Login page URL */
+    loginUrl?: string;
+    /** Text that appears when logged in (e.g., "Logout") */
+    loggedInIndicator?: string;
+    /** Text that appears when logged out (e.g., "Sign In") */
+    loggedOutIndicator?: string;
+    /** Session expiry detection rules */
+    sessionExpiry?: {
+        /** HTTP status codes that indicate session expired */
+        statusCodes?: number[];
+        /** URL pattern that indicates redirect to login */
+        redirectPattern?: string;
+        /** Page content that indicates session expired */
+        pageContent?: string;
+    };
+}
+/**
+ * Encrypt data with AES-256-GCM.
+ *
+ * @param data - Plaintext data to encrypt
+ * @param passphrase - Passphrase for key derivation
+ * @returns JSON string of EncryptedData
+ */
+declare function encrypt(data: string, passphrase: string): string;
+/**
+ * Decrypt data encrypted with encrypt().
+ *
+ * @param encrypted - JSON string from encrypt()
+ * @param passphrase - Passphrase used during encryption
+ * @returns Decrypted plaintext
+ * @throws Error if passphrase is wrong or data is tampered
+ */
+declare function decrypt(encrypted: string, passphrase: string): string;
+/**
+ * Encrypt credentials to a storable string.
+ */
+declare function encryptCredentials(credentials: Credentials, passphrase: string): string;
+/**
+ * Decrypt credentials from a stored string.
+ */
+declare function decryptCredentials(encrypted: string, passphrase: string): Credentials;
+/**
+ * Encrypt browser storage state (cookies, localStorage, etc.).
+ * The state is the JSON output from Playwright's context.storageState().
+ */
+declare function encryptStorageState(storageState: string, passphrase: string): string;
+/**
+ * Decrypt browser storage state.
+ */
+declare function decryptStorageState(encrypted: string, passphrase: string): string;
+/**
+ * Get passphrase from environment or throw.
+ *
+ * In CI/CD, set VULCN_KEY env var.
+ * In interactive mode, the CLI should prompt and pass the value here.
+ */
+declare function getPassphrase(interactive?: string): string;
+
+/**
+ * Vulcn Session Format v2
+ *
+ * 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)
+ */
+
+/** 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 */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Form data (for POST) */
+    body?: string;
+    /** Content type */
+    contentType?: string;
+    /** Which form field is injectable */
+    injectableField?: string;
+    /** 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 };

package/dist/index.d.ts

@@ -124,12 +124,22 @@ interface PluginHooks {
     onRecordStep?: (step: Step, ctx: RecordContext) => Promise<Step>;
     /** Called when recording ends, can transform session */
     onRecordEnd?: (session: Session, ctx: RecordContext) => Promise<Session>;
+    /** Called once when a scan starts (before any session is executed) */
+    onScanStart?: (ctx: ScanContext) => Promise<void>;
+    /** Called once when a scan ends (after all sessions have executed) */
+    onScanEnd?: (result: RunResult, ctx: ScanContext) => Promise<RunResult>;
     /** Called when run starts */
     onRunStart?: (ctx: RunContext$1) => Promise<void>;
     /** Called before each payload is injected, can transform payload */
     onBeforePayload?: (payload: string, step: Step, ctx: RunContext$1) => Promise<string>;
     /** Called after payload injection, for detection */
     onAfterPayload?: (ctx: DetectContext) => Promise<Finding[]>;
+    /**
+     * Called before the browser/driver is closed.
+     * Plugins should await any pending async work here (e.g., flush
+     * in-flight response handlers that need browser access).
+     */
+    onBeforeClose?: (ctx: PluginContext) => Promise<void>;
     /** Called when run ends, can transform results */
     onRunEnd?: (result: RunResult, ctx: RunContext$1) => Promise<RunResult>;
     /** Called when JavaScript alert/confirm/prompt appears */
@@ -169,8 +179,14 @@ interface PluginContext {
     engine: EngineInfo;
     /** Shared payload registry - loaders add payloads here */
     payloads: RuntimePayload[];
-    /** Shared findings collection - detectors add findings here */
+    /** Shared findings collection (read-only view, use addFinding to add) */
     findings: Finding[];
+    /**
+     * Add a finding through the proper callback chain.
+     * Plugins should use this instead of pushing to findings[] directly,
+     * so consumers (CLI, worker) get notified via onFinding callbacks.
+     */
+    addFinding: (finding: Finding) => void;
     /** Scoped logger */
     logger: PluginLogger;
     /** Fetch API for network requests */
@@ -194,6 +210,17 @@ interface RunContext$1 extends PluginContext {
     /** Whether running headless */
     headless: boolean;
 }
+/**
+ * Context for scan-level hooks (wraps all sessions)
+ */
+interface ScanContext extends PluginContext {
+    /** All sessions in this scan */
+    sessions: Session[];
+    /** Whether running headless */
+    headless: boolean;
+    /** Total sessions count */
+    sessionCount: number;
+}
 /**
  * Context for detection hooks
  */
@@ -438,6 +465,8 @@ interface CrawlOptions {
     pageTimeout?: number;
     /** Only crawl pages under the same origin (default: true) */
     sameOrigin?: boolean;
+    /** Playwright storage state JSON for authenticated crawling */
+    storageState?: string;
     /** Callback when a page is crawled */
     onPageCrawled?: (url: string, formsFound: number) => void;
 }
@@ -451,6 +480,18 @@ interface RunOptions {
     onFinding?: (finding: Finding) => void;
     /** Callback for step completion */
     onStepComplete?: (stepId: string, payloadCount: number) => void;
+    /**
+     * Called by the driver runner after the page/environment is ready.
+     * The driver-manager uses this to fire plugin onRunStart hooks
+     * with the real page object (instead of null).
+     */
+    onPageReady?: (page: unknown) => Promise<void>;
+    /**
+     * Called by the driver runner before closing the browser/environment.
+     * The driver-manager uses this to fire plugin onBeforeClose hooks
+     * so plugins can flush pending async work.
+     */
+    onBeforeClose?: (page: unknown) => Promise<void>;
     /** Driver-specific options */
     [key: string]: unknown;
 }
@@ -627,8 +668,27 @@ declare class DriverManager {
     /**
      * Execute a session
      * Invokes plugin hooks (onRunStart, onRunEnd) around the driver runner.
+     * Plugin onRunStart is deferred until the driver signals the page is ready
+     * via the onPageReady callback, ensuring plugins get a real page object.
      */
     execute(session: Session, pluginManager: PluginManager, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Execute multiple sessions with a shared browser (scan-level orchestration).
+     *
+     * This is the preferred entry point for running a full scan. It:
+     * 1. Launches ONE browser for the entire scan
+     * 2. Passes the browser to each session's runner via options.browser
+     * 3. Each session creates its own context (lightweight, isolated cookies)
+     * 4. Aggregates results across all sessions
+     * 5. Closes the browser once at the end
+     *
+     * This is 5-10x faster than calling execute() per session because
+     * launching a browser takes 2-3 seconds.
+     */
+    executeScan(sessions: Session[], pluginManager: PluginManager, options?: RunOptions): Promise<{
+        results: RunResult[];
+        aggregate: RunResult;
+    }>;
     /**
      * Validate driver structure
      */
@@ -643,4 +703,215 @@ declare class DriverManager {
  */
 declare const driverManager: DriverManager;
 
-export { type CrawlOptions, 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 };
+/**
+ * Vulcn Auth Module
+ *
+ * Handles credential encryption/decryption and auth state management.
+ *
+ * Security:
+ * - AES-256-GCM encryption for credentials at rest
+ * - PBKDF2 key derivation from passphrase
+ * - Reads passphrase from VULCN_KEY env var (CI/CD) or interactive prompt
+ * - Auth state (cookies, localStorage) encrypted separately
+ */
+/** Form-based login credentials */
+interface FormCredentials {
+    type: "form";
+    username: string;
+    password: string;
+    /** Custom login URL (if different from target) */
+    loginUrl?: string;
+    /** Custom CSS selector for username field */
+    userSelector?: string;
+    /** Custom CSS selector for password field */
+    passSelector?: string;
+}
+/** Header-based authentication (API keys, Bearer tokens) */
+interface HeaderCredentials {
+    type: "header";
+    headers: Record<string, string>;
+}
+/** All credential types */
+type Credentials = FormCredentials | HeaderCredentials;
+/** Auth configuration for a scan */
+interface AuthConfig {
+    /** Auth strategy */
+    strategy: "storage-state" | "header";
+    /** Login page URL */
+    loginUrl?: string;
+    /** Text that appears when logged in (e.g., "Logout") */
+    loggedInIndicator?: string;
+    /** Text that appears when logged out (e.g., "Sign In") */
+    loggedOutIndicator?: string;
+    /** Session expiry detection rules */
+    sessionExpiry?: {
+        /** HTTP status codes that indicate session expired */
+        statusCodes?: number[];
+        /** URL pattern that indicates redirect to login */
+        redirectPattern?: string;
+        /** Page content that indicates session expired */
+        pageContent?: string;
+    };
+}
+/**
+ * Encrypt data with AES-256-GCM.
+ *
+ * @param data - Plaintext data to encrypt
+ * @param passphrase - Passphrase for key derivation
+ * @returns JSON string of EncryptedData
+ */
+declare function encrypt(data: string, passphrase: string): string;
+/**
+ * Decrypt data encrypted with encrypt().
+ *
+ * @param encrypted - JSON string from encrypt()
+ * @param passphrase - Passphrase used during encryption
+ * @returns Decrypted plaintext
+ * @throws Error if passphrase is wrong or data is tampered
+ */
+declare function decrypt(encrypted: string, passphrase: string): string;
+/**
+ * Encrypt credentials to a storable string.
+ */
+declare function encryptCredentials(credentials: Credentials, passphrase: string): string;
+/**
+ * Decrypt credentials from a stored string.
+ */
+declare function decryptCredentials(encrypted: string, passphrase: string): Credentials;
+/**
+ * Encrypt browser storage state (cookies, localStorage, etc.).
+ * The state is the JSON output from Playwright's context.storageState().
+ */
+declare function encryptStorageState(storageState: string, passphrase: string): string;
+/**
+ * Decrypt browser storage state.
+ */
+declare function decryptStorageState(encrypted: string, passphrase: string): string;
+/**
+ * Get passphrase from environment or throw.
+ *
+ * In CI/CD, set VULCN_KEY env var.
+ * In interactive mode, the CLI should prompt and pass the value here.
+ */
+declare function getPassphrase(interactive?: string): string;
+
+/**
+ * Vulcn Session Format v2
+ *
+ * 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)
+ */
+
+/** 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 */
+    method: string;
+    /** Full URL */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Form data (for POST) */
+    body?: string;
+    /** Content type */
+    contentType?: string;
+    /** Which form field is injectable */
+    injectableField?: string;
+    /** 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 };