@vulcn/engine 0.5.0 → 0.8.0

package/dist/index.js

@@ -156,23 +156,17 @@ var DriverManager = class {
   /**
    * 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.
    */
   async execute(session, pluginManager2, options = {}) {
     const driver = this.getForSession(session);
     const findings = [];
     const logger = this.createLogger(driver.name);
-    const ctx = {
-      session,
-      pluginManager: pluginManager2,
-      payloads: pluginManager2.getPayloads(),
-      findings,
-      addFinding: (finding) => {
-        findings.push(finding);
-        pluginManager2.addFinding(finding);
-        options.onFinding?.(finding);
-      },
-      logger,
-      options
+    const addFinding = (finding) => {
+      findings.push(finding);
+      pluginManager2.addFinding(finding);
+      options.onFinding?.(finding);
     };
     const pluginCtx = {
       session,
@@ -182,21 +176,57 @@ var DriverManager = class {
       engine: { version: "0.3.0", pluginApiVersion: 1 },
       payloads: pluginManager2.getPayloads(),
       findings,
+      addFinding,
       logger,
       fetch: globalThis.fetch
     };
-    for (const loaded of pluginManager2.getPlugins()) {
-      if (loaded.enabled && loaded.plugin.hooks?.onRunStart) {
-        try {
-          await loaded.plugin.hooks.onRunStart({
-            ...pluginCtx,
-            config: loaded.config
-          });
-        } catch (err) {
-          logger.warn(`Plugin ${loaded.plugin.name} onRunStart failed: ${err}`);
+    const ctx = {
+      session,
+      pluginManager: pluginManager2,
+      payloads: pluginManager2.getPayloads(),
+      findings,
+      addFinding,
+      logger,
+      options: {
+        ...options,
+        // Provide onPageReady callback — fires plugin onRunStart hooks
+        // with the real page object once the driver has created it
+        onPageReady: async (page) => {
+          pluginCtx.page = page;
+          for (const loaded of pluginManager2.getPlugins()) {
+            if (loaded.enabled && loaded.plugin.hooks?.onRunStart) {
+              try {
+                await loaded.plugin.hooks.onRunStart({
+                  ...pluginCtx,
+                  config: loaded.config
+                });
+              } catch (err) {
+                logger.warn(
+                  `Plugin ${loaded.plugin.name} onRunStart failed: ${err}`
+                );
+              }
+            }
+          }
+        },
+        // Fires before browser closes — lets plugins flush pending async work
+        onBeforeClose: async (_page) => {
+          for (const loaded of pluginManager2.getPlugins()) {
+            if (loaded.enabled && loaded.plugin.hooks?.onBeforeClose) {
+              try {
+                await loaded.plugin.hooks.onBeforeClose({
+                  ...pluginCtx,
+                  config: loaded.config
+                });
+              } catch (err) {
+                logger.warn(
+                  `Plugin ${loaded.plugin.name} onBeforeClose failed: ${err}`
+                );
+              }
+            }
+          }
         }
       }
-    }
+    };
     let result = await driver.runner.execute(session, ctx);
     for (const loaded of pluginManager2.getPlugins()) {
       if (loaded.enabled && loaded.plugin.hooks?.onRunEnd) {
@@ -213,6 +243,109 @@ var DriverManager = class {
     }
     return result;
   }
+  /**
+   * 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.
+   */
+  async executeScan(sessions, pluginManager2, options = {}) {
+    if (sessions.length === 0) {
+      const empty = {
+        findings: [],
+        stepsExecuted: 0,
+        payloadsTested: 0,
+        duration: 0,
+        errors: ["No sessions to execute"]
+      };
+      return { results: [], aggregate: empty };
+    }
+    const startTime = Date.now();
+    const results = [];
+    const allFindings = [];
+    let totalSteps = 0;
+    let totalPayloads = 0;
+    const allErrors = [];
+    const firstDriver = this.getForSession(sessions[0]);
+    let sharedBrowser = null;
+    if (firstDriver.name === "browser") {
+      try {
+        const driverPkg = "@vulcn/driver-browser";
+        const { launchBrowser } = await import(
+          /* @vite-ignore */
+          driverPkg
+        );
+        const browserType = sessions[0].driverConfig.browser ?? "chromium";
+        const headless = options.headless ?? true;
+        const result = await launchBrowser({
+          browser: browserType,
+          headless
+        });
+        sharedBrowser = result.browser;
+      } catch {
+      }
+    }
+    try {
+      await pluginManager2.callHook("onScanStart", async (hook, ctx) => {
+        const scanCtx = {
+          ...ctx,
+          sessions,
+          headless: options.headless ?? true,
+          sessionCount: sessions.length
+        };
+        await hook(scanCtx);
+      });
+      for (const session of sessions) {
+        const sessionOptions = {
+          ...options,
+          ...sharedBrowser ? { browser: sharedBrowser } : {}
+        };
+        const result = await this.execute(
+          session,
+          pluginManager2,
+          sessionOptions
+        );
+        results.push(result);
+        allFindings.push(...result.findings);
+        totalSteps += result.stepsExecuted;
+        totalPayloads += result.payloadsTested;
+        allErrors.push(...result.errors);
+      }
+    } finally {
+      if (sharedBrowser && typeof sharedBrowser.close === "function") {
+        await sharedBrowser.close();
+      }
+    }
+    const aggregate = {
+      findings: allFindings,
+      stepsExecuted: totalSteps,
+      payloadsTested: totalPayloads,
+      duration: Date.now() - startTime,
+      errors: allErrors
+    };
+    let finalAggregate = aggregate;
+    finalAggregate = await pluginManager2.callHookPipe(
+      "onScanEnd",
+      finalAggregate,
+      async (hook, value, ctx) => {
+        const scanCtx = {
+          ...ctx,
+          sessions,
+          headless: options.headless ?? true,
+          sessionCount: sessions.length
+        };
+        return await hook(value, scanCtx);
+      }
+    );
+    return { results, aggregate: finalAggregate };
+  }
   /**
    * Validate driver structure
    */
@@ -487,6 +620,9 @@ var PluginManager = class {
       engine: engineInfo,
       payloads: this.sharedPayloads,
       findings: this.sharedFindings,
+      addFinding: (finding) => {
+        this.sharedFindings.push(finding);
+      },
       logger: this.createLogger("plugin"),
       fetch: globalThis.fetch
     };
@@ -583,12 +719,269 @@ var PluginManager = class {
   }
 };
 var pluginManager = new PluginManager();
+
+// src/auth.ts
+import {
+  randomBytes,
+  createCipheriv,
+  createDecipheriv,
+  pbkdf2Sync
+} from "crypto";
+var ALGORITHM = "aes-256-gcm";
+var KEY_LENGTH = 32;
+var IV_LENGTH = 16;
+var SALT_LENGTH = 32;
+var PBKDF2_ITERATIONS = 1e5;
+var PBKDF2_DIGEST = "sha512";
+function deriveKey(passphrase, salt) {
+  return pbkdf2Sync(
+    passphrase,
+    salt,
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    PBKDF2_DIGEST
+  );
+}
+function encrypt(data, passphrase) {
+  const salt = randomBytes(SALT_LENGTH);
+  const iv = randomBytes(IV_LENGTH);
+  const key = deriveKey(passphrase, salt);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  let encrypted = cipher.update(data, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  const tag = cipher.getAuthTag();
+  const payload = {
+    version: 1,
+    salt: salt.toString("hex"),
+    iv: iv.toString("hex"),
+    tag: tag.toString("hex"),
+    data: encrypted,
+    iterations: PBKDF2_ITERATIONS
+  };
+  return JSON.stringify(payload);
+}
+function decrypt(encrypted, passphrase) {
+  const payload = JSON.parse(encrypted);
+  if (payload.version !== 1) {
+    throw new Error(`Unsupported encryption version: ${payload.version}`);
+  }
+  const salt = Buffer.from(payload.salt, "hex");
+  const iv = Buffer.from(payload.iv, "hex");
+  const tag = Buffer.from(payload.tag, "hex");
+  const key = deriveKey(passphrase, salt);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+  let decrypted = decipher.update(payload.data, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+}
+function encryptCredentials(credentials, passphrase) {
+  return encrypt(JSON.stringify(credentials), passphrase);
+}
+function decryptCredentials(encrypted, passphrase) {
+  const json = decrypt(encrypted, passphrase);
+  return JSON.parse(json);
+}
+function encryptStorageState(storageState, passphrase) {
+  return encrypt(storageState, passphrase);
+}
+function decryptStorageState(encrypted, passphrase) {
+  return decrypt(encrypted, passphrase);
+}
+function getPassphrase(interactive) {
+  if (interactive) return interactive;
+  const envKey = process.env.VULCN_KEY;
+  if (envKey) return envKey;
+  throw new Error(
+    "No passphrase provided. Set VULCN_KEY environment variable or pass --passphrase."
+  );
+}
+
+// src/session.ts
+import { readFile as readFile2, writeFile, mkdir, readdir } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join, basename } from "path";
+import { parse as parse2, stringify as stringify2 } from "yaml";
+async function loadSessionDir(dirPath) {
+  const manifestPath = join(dirPath, "manifest.yml");
+  if (!existsSync2(manifestPath)) {
+    throw new Error(
+      `No manifest.yml found in ${dirPath}. Is this a v2 session directory?`
+    );
+  }
+  const manifestYaml = await readFile2(manifestPath, "utf-8");
+  const manifest = parse2(manifestYaml);
+  if (manifest.version !== "2") {
+    throw new Error(
+      `Unsupported session format version: ${manifest.version}. Expected "2".`
+    );
+  }
+  let authConfig;
+  if (manifest.auth?.configFile) {
+    const authPath = join(dirPath, manifest.auth.configFile);
+    if (existsSync2(authPath)) {
+      const authYaml = await readFile2(authPath, "utf-8");
+      authConfig = parse2(authYaml);
+    }
+  }
+  const sessions = [];
+  for (const ref of manifest.sessions) {
+    if (ref.injectable === false) continue;
+    const sessionPath = join(dirPath, ref.file);
+    if (!existsSync2(sessionPath)) {
+      console.warn(`Session file not found: ${sessionPath}, skipping`);
+      continue;
+    }
+    const sessionYaml = await readFile2(sessionPath, "utf-8");
+    const sessionData = parse2(sessionYaml);
+    const session = {
+      name: sessionData.name ?? basename(ref.file, ".yml"),
+      driver: manifest.driver,
+      driverConfig: {
+        ...manifest.driverConfig,
+        startUrl: resolveUrl(
+          manifest.target,
+          sessionData.page
+        )
+      },
+      steps: sessionData.steps ?? [],
+      metadata: {
+        recordedAt: manifest.recordedAt,
+        version: "2",
+        manifestDir: dirPath
+      }
+    };
+    sessions.push(session);
+  }
+  return { manifest, sessions, authConfig };
+}
+function isSessionDir(path) {
+  return existsSync2(join(path, "manifest.yml"));
+}
+function looksLikeSessionDir(path) {
+  return path.endsWith(".vulcn") || path.endsWith(".vulcn/");
+}
+async function saveSessionDir(dirPath, options) {
+  await mkdir(join(dirPath, "sessions"), { recursive: true });
+  const sessionRefs = [];
+  for (const session of options.sessions) {
+    const safeName = slugify(session.name);
+    const fileName = `sessions/${safeName}.yml`;
+    const sessionPath = join(dirPath, fileName);
+    const startUrl = session.driverConfig.startUrl;
+    const page = startUrl ? startUrl.replace(options.target, "").replace(/^\//, "/") : void 0;
+    const sessionData = {
+      name: session.name,
+      ...page ? { page } : {},
+      steps: session.steps
+    };
+    await writeFile(sessionPath, stringify2(sessionData), "utf-8");
+    const hasInjectable = session.steps.some(
+      (s) => s.type === "browser.input" && s.injectable !== false
+    );
+    sessionRefs.push({
+      file: fileName,
+      injectable: hasInjectable
+    });
+  }
+  if (options.authConfig) {
+    await mkdir(join(dirPath, "auth"), { recursive: true });
+    await writeFile(
+      join(dirPath, "auth", "config.yml"),
+      stringify2(options.authConfig),
+      "utf-8"
+    );
+  }
+  if (options.encryptedState) {
+    await mkdir(join(dirPath, "auth"), { recursive: true });
+    await writeFile(
+      join(dirPath, "auth", "state.enc"),
+      options.encryptedState,
+      "utf-8"
+    );
+  }
+  if (options.requests && options.requests.length > 0) {
+    await mkdir(join(dirPath, "requests"), { recursive: true });
+    for (const req of options.requests) {
+      const safeName = slugify(req.sessionName);
+      await writeFile(
+        join(dirPath, "requests", `${safeName}.json`),
+        JSON.stringify(req, null, 2),
+        "utf-8"
+      );
+    }
+  }
+  const manifest = {
+    version: "2",
+    name: options.name,
+    target: options.target,
+    recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    driver: options.driver,
+    driverConfig: options.driverConfig,
+    ...options.authConfig ? {
+      auth: {
+        strategy: options.authConfig.strategy,
+        configFile: "auth/config.yml",
+        stateFile: options.encryptedState ? "auth/state.enc" : void 0,
+        loggedInIndicator: options.authConfig.loggedInIndicator,
+        loggedOutIndicator: options.authConfig.loggedOutIndicator
+      }
+    } : {},
+    sessions: sessionRefs,
+    scan: {
+      tier: "auto",
+      parallel: 1,
+      timeout: 12e4
+    }
+  };
+  await writeFile(join(dirPath, "manifest.yml"), stringify2(manifest), "utf-8");
+}
+async function readAuthState(dirPath) {
+  const statePath = join(dirPath, "auth", "state.enc");
+  if (!existsSync2(statePath)) return null;
+  return readFile2(statePath, "utf-8");
+}
+async function readCapturedRequests(dirPath) {
+  const requestsDir = join(dirPath, "requests");
+  if (!existsSync2(requestsDir)) return [];
+  const files = await readdir(requestsDir);
+  const requests = [];
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const content = await readFile2(join(requestsDir, file), "utf-8");
+    requests.push(JSON.parse(content));
+  }
+  return requests;
+}
+function resolveUrl(target, page) {
+  if (!page) return target;
+  if (page.startsWith("http")) return page;
+  const base = target.replace(/\/$/, "");
+  const path = page.startsWith("/") ? page : `/${page}`;
+  return `${base}${path}`;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
 export {
   DRIVER_API_VERSION,
   DriverManager,
   PLUGIN_API_VERSION,
   PluginManager,
+  decrypt,
+  decryptCredentials,
+  decryptStorageState,
   driverManager,
-  pluginManager
+  encrypt,
+  encryptCredentials,
+  encryptStorageState,
+  getPassphrase,
+  isSessionDir,
+  loadSessionDir,
+  looksLikeSessionDir,
+  pluginManager,
+  readAuthState,
+  readCapturedRequests,
+  saveSessionDir
 };
 //# sourceMappingURL=index.js.map