vigthoria-cli 1.13.26 → 1.13.30

package/dist/utils/preview-screenshot-adapter.js

@@ -1,103 +1,312 @@
-import { pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { redactSensitiveText } from './secret-policy.js';
+import { pathToFileURL } from 'node:url';
+import { redactSensitiveText, safeChildProcessEnv } from './secret-policy.js';
 import { createRuntimeTempDirectory, removeRuntimeTempDirectory } from './runtime-temp.js';
-export function resolvePreviewBrowserExecutable(puppeteer, environment = process.env, platform = process.platform, exists = fs.existsSync) {
-    if (typeof puppeteer.executablePath !== 'function')
-        return { headless: 'shell', source: 'injected' };
+const SCREENSHOT_WIDTH = 800;
+const SCREENSHOT_HEIGHT = 600;
+const SCREENSHOT_MAX_BYTES = 10 * 1024 * 1024;
+const BROWSER_TIMEOUT_MS = 30_000;
+// Chromium creates short-lived files below TMPDIR while starting. Keep enough
+// room below the 108-byte POSIX sockaddr_un ceiling without rejecting normal
+// per-user Vigthoria roots (for example ~/.vigthoria/tmp/browser-*/scratch).
+const POSIX_BROWSER_SCRATCH_MAX_BYTES = 76;
+export function resolvePreviewBrowserExecutable(environment = process.env, platform = process.platform, exists = fs.existsSync) {
+    const candidates = platform === 'win32'
+        ? [
+            ...[environment['PROGRAMFILES(X86)'], environment.ProgramFiles, environment.LOCALAPPDATA]
+                .filter((value) => typeof value === 'string' && value.length > 0)
+                .flatMap((base) => [
+                path.win32.join(base, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+                path.win32.join(base, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+            ]),
+        ]
+        : platform === 'darwin'
+            ? [
+                '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+                '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+                '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            ]
+            : [
+                '/usr/bin/google-chrome',
+                '/usr/bin/google-chrome-stable',
+                '/usr/bin/microsoft-edge',
+                '/usr/bin/microsoft-edge-stable',
+                '/usr/bin/chromium',
+                '/usr/bin/chromium-browser',
+                '/snap/bin/chromium',
+            ];
+    for (const candidate of candidates) {
+        if (exists(candidate))
+            return { executablePath: candidate, source: 'system' };
+    }
+    return null;
+}
+async function terminateBrowserProcess(child, platform) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (platform === 'win32') {
+        const taskkill = path.win32.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe');
+        await new Promise((resolve) => {
+            const killer = spawn(taskkill, ['/PID', String(pid), '/T', '/F'], {
+                stdio: 'ignore', windowsHide: true, env: safeChildProcessEnv(),
+            });
+            const timer = setTimeout(() => {
+                try {
+                    killer.kill();
+                }
+                catch { /* helper already exited */ }
+                try {
+                    child.kill();
+                }
+                catch { /* exact child already exited */ }
+                resolve();
+            }, 5_000);
+            killer.once('error', () => { clearTimeout(timer); try {
+                child.kill();
+            }
+            catch { /* exact child only */ } resolve(); });
+            killer.once('exit', () => { clearTimeout(timer); resolve(); });
+        });
+        return;
+    }
     try {
-        const packaged = puppeteer.executablePath();
-        if (packaged && exists(packaged))
-            return { executablePath: packaged, headless: 'shell', source: 'packaged' };
+        process.kill(-pid, 'SIGTERM');
     }
     catch {
-        // Continue to trusted platform browser locations.
-    }
-    if (platform !== 'win32')
-        return null;
-    const bases = [environment['PROGRAMFILES(X86)'], environment.ProgramFiles, environment.LOCALAPPDATA]
-        .filter((value) => typeof value === 'string' && value.length > 0);
-    const relatives = [
-        ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
-        ['Google', 'Chrome', 'Application', 'chrome.exe'],
-    ];
-    for (const base of bases) {
-        for (const relative of relatives) {
-            const candidate = path.win32.join(base, ...relative);
-            if (exists(candidate))
-                return { executablePath: candidate, headless: true, source: 'system' };
+        try {
+            child.kill('SIGTERM');
         }
+        catch { /* already gone */ }
     }
-    return null;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    try {
+        process.kill(-pid, 0);
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* group exited */ }
 }
-function withTimeout(promise, timeoutMs, label) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+export const runPreviewBrowser = (executablePath, args, platform, environment = process.env) => new Promise((resolve, reject) => {
+    const child = spawn(executablePath, [...args], {
+        stdio: 'ignore',
+        windowsHide: true,
+        env: safeChildProcessEnv(environment),
+        detached: platform !== 'win32',
+    });
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        error ? reject(error) : resolve();
+    };
+    const timer = setTimeout(() => {
+        void terminateBrowserProcess(child, platform).finally(() => finish(new Error(`browser screenshot timed out after ${BROWSER_TIMEOUT_MS}ms`)));
+    }, BROWSER_TIMEOUT_MS);
+    child.once('error', (error) => finish(error));
+    child.once('exit', (code, signal) => {
+        if (code === 0)
+            finish();
+        else
+            finish(new Error(`browser screenshot process exited with ${signal || code}`));
     });
+});
+function pngCrc32(data) {
+    let crc = 0xffffffff;
+    for (const byte of data) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit += 1) {
+            crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function validatePng(filePath) {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size < 57 || stat.size > SCREENSHOT_MAX_BYTES) {
+        throw new Error('browser did not produce a bounded PNG screenshot');
+    }
+    const bytes = fs.readFileSync(filePath);
+    if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+        throw new Error('browser screenshot output is not a PNG file');
+    }
+    let offset = 8;
+    let chunks = 0;
+    let sawHeader = false;
+    let sawImageData = false;
+    let sawEnd = false;
+    while (offset + 12 <= bytes.length && chunks < 4096) {
+        const length = bytes.readUInt32BE(offset);
+        const chunkEnd = offset + 12 + length;
+        if (chunkEnd > bytes.length)
+            throw new Error('browser screenshot PNG contains a truncated chunk');
+        const typeBytes = bytes.subarray(offset + 4, offset + 8);
+        const type = typeBytes.toString('ascii');
+        const data = bytes.subarray(offset + 8, offset + 8 + length);
+        const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+        if (pngCrc32(Buffer.concat([typeBytes, data])) !== expectedCrc) {
+            throw new Error('browser screenshot PNG contains an invalid chunk checksum');
+        }
+        chunks += 1;
+        if (chunks === 1 && (type !== 'IHDR' || length !== 13)) {
+            throw new Error('browser screenshot PNG has no valid leading IHDR chunk');
+        }
+        if (type === 'IHDR') {
+            if (sawHeader || length !== 13)
+                throw new Error('browser screenshot PNG has an invalid IHDR chunk');
+            sawHeader = true;
+            const width = data.readUInt32BE(0);
+            const height = data.readUInt32BE(4);
+            if (width !== SCREENSHOT_WIDTH || height !== SCREENSHOT_HEIGHT) {
+                throw new Error(`browser screenshot dimensions were ${width}x${height}; expected ${SCREENSHOT_WIDTH}x${SCREENSHOT_HEIGHT}`);
+            }
+        }
+        else if (type === 'IDAT') {
+            if (!sawHeader || length === 0)
+                throw new Error('browser screenshot PNG has invalid image data');
+            sawImageData = true;
+        }
+        else if (type === 'IEND') {
+            if (length !== 0 || !sawImageData)
+                throw new Error('browser screenshot PNG has an invalid IEND chunk');
+            sawEnd = true;
+            offset = chunkEnd;
+            break;
+        }
+        offset = chunkEnd;
+    }
+    if (!sawHeader || !sawImageData || !sawEnd || offset !== bytes.length) {
+        throw new Error('browser screenshot PNG is incomplete or contains trailing data');
+    }
 }
-export class OptionalPuppeteerScreenshotAdapter {
-    loadPuppeteer;
+function isTransientBrowserFailure(result) {
+    if (result.captured || !result.error || /profile cleanup failed/i.test(result.error))
+        return false;
+    return /(?:process exited with (?:SIG[A-Z]+|[1-9][0-9]*)|timed out|\bE(?:ACCES|PERM|BUSY|AGAIN)\b|resource temporarily unavailable)/i.test(result.error);
+}
+/** Dependency-free system-browser adapter. No browser download or archive
+ * extractor is shipped, and only fixed operating-system installation paths
+ * are eligible.
+ */
+export class SystemBrowserScreenshotAdapter {
     environment;
     allocateTemp;
     releaseTemp;
     platform;
-    constructor(loadPuppeteer = () => import('puppeteer'), environment = process.env, allocateTemp = createRuntimeTempDirectory, releaseTemp = removeRuntimeTempDirectory, platform = process.platform) {
-        this.loadPuppeteer = loadPuppeteer;
+    exists;
+    runner;
+    constructor(environment = process.env, allocateTemp = createRuntimeTempDirectory, releaseTemp = removeRuntimeTempDirectory, platform = process.platform, exists = fs.existsSync, runner = runPreviewBrowser) {
         this.environment = environment;
         this.allocateTemp = allocateTemp;
         this.releaseTemp = releaseTemp;
         this.platform = platform;
+        this.exists = exists;
+        this.runner = runner;
     }
     async capture(entryAbsolutePath, screenshotPath) {
         if (this.environment.VIGTHORIA_DISABLE_PREVIEW_SCREENSHOT === '1') {
             return { captured: false, error: 'screenshot capture explicitly unavailable' };
         }
+        const resolution = resolvePreviewBrowserExecutable(this.environment, this.platform, this.exists);
+        if (!resolution) {
+            return { captured: false, error: 'required system browser is unavailable; install Microsoft Edge, Chrome, or Chromium' };
+        }
+        // Headless Chromium-family processes can fail transiently while a previous
+        // profile/process is releasing OS resources. Screenshot generation is a
+        // local idempotent operation, so one fresh-profile retry is safe. Invalid
+        // proof bytes and cleanup failures are never retried or credited.
+        let lastResult = { captured: false, error: 'browser screenshot was not attempted' };
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            lastResult = await this.captureOnce(resolution, entryAbsolutePath, screenshotPath);
+            if (lastResult.captured || !isTransientBrowserFailure(lastResult))
+                return lastResult;
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        return lastResult;
+    }
+    async captureOnce(resolution, entryAbsolutePath, screenshotPath) {
+        let browserProfile = null;
+        let result;
         try {
-            const loaded = await this.loadPuppeteer().catch(() => null);
-            const puppeteer = (loaded?.default || loaded);
-            if (!puppeteer || typeof puppeteer.launch !== 'function') {
-                return { captured: false, error: 'required Puppeteer screenshot runtime is not installed' };
+            browserProfile = this.allocateTemp('browser-', 128 * 1024 * 1024);
+            const browserUserData = path.join(browserProfile, 'profile');
+            const browserScratch = path.join(browserProfile, 'scratch');
+            if (this.platform !== 'win32' && Buffer.byteLength(browserScratch) > POSIX_BROWSER_SCRATCH_MAX_BYTES) {
+                throw new Error('managed browser temporary path is too long; configure a shorter dedicated VIGTHORIA_TEMP_DIR');
             }
-            const browserResolution = resolvePreviewBrowserExecutable(puppeteer, this.environment, this.platform);
-            if (!browserResolution) {
-                return { captured: false, error: 'required browser executable is unavailable; install Chrome/Edge or the packaged Puppeteer browser' };
+            fs.mkdirSync(browserUserData, { recursive: false, mode: 0o700 });
+            fs.mkdirSync(browserScratch, { recursive: false, mode: 0o700 });
+            fs.mkdirSync(path.dirname(screenshotPath), { recursive: true, mode: 0o700 });
+            try {
+                fs.unlinkSync(screenshotPath);
             }
-            const browserProfile = this.allocateTemp('browser-');
-            let browser = null;
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+            const args = [
+                '--headless=new',
+                '--disable-gpu',
+                '--disable-dev-shm-usage',
+                '--hide-scrollbars',
+                '--no-first-run',
+                '--no-default-browser-check',
+                '--disable-background-networking',
+                '--disable-component-update',
+                '--disable-sync',
+                '--metrics-recording-only',
+                '--proxy-server=http://127.0.0.1:9',
+                '--proxy-bypass-list=<-loopback>',
+                `--user-data-dir=${browserUserData}`,
+                `--window-size=${SCREENSHOT_WIDTH},${SCREENSHOT_HEIGHT}`,
+                `--screenshot=${screenshotPath}`,
+                '--allow-file-access-from-files',
+                pathToFileURL(entryAbsolutePath).toString(),
+            ];
+            const browserEnvironment = safeChildProcessEnv(this.environment, {
+                TMPDIR: browserScratch,
+                TMP: browserScratch,
+                TEMP: browserScratch,
+            });
+            await this.runner(resolution.executablePath, args, this.platform, browserEnvironment);
+            validatePng(screenshotPath);
+            result = { captured: true };
+        }
+        catch (error) {
             try {
-                browser = await withTimeout(puppeteer.launch({
-                    headless: browserResolution.headless,
-                    args: ['--no-sandbox', '--disable-setuid-sandbox'],
-                    userDataDir: browserProfile,
-                    executablePath: browserResolution.executablePath,
-                    timeout: 20_000,
-                    protocolTimeout: 20_000,
-                }), 25_000, 'browser launch');
-                const page = await withTimeout(browser.newPage(), 10_000, 'browser page creation');
-                await withTimeout(page.setViewport({ width: 800, height: 600, deviceScaleFactor: 1 }), 10_000, 'browser viewport setup');
-                await page.goto(pathToFileURL(entryAbsolutePath).toString(), { waitUntil: 'networkidle0', timeout: 20_000 });
-                await withTimeout(page.screenshot({ path: screenshotPath, fullPage: false }), 20_000, 'screenshot capture');
+                fs.unlinkSync(screenshotPath);
             }
-            finally {
-                if (browser) {
+            catch { /* no failed proof artifact */ }
+            result = { captured: false, error: redactSensitiveText(error instanceof Error ? error.message : String(error)) };
+        }
+        finally {
+            if (browserProfile) {
+                try {
+                    this.releaseTemp(browserProfile);
+                }
+                catch {
+                    await new Promise((resolve) => setTimeout(resolve, 150));
                     try {
-                        await withTimeout(browser.close(), 5_000, 'browser shutdown');
+                        this.releaseTemp(browserProfile);
                     }
-                    catch {
+                    catch (cleanupError) {
                         try {
-                            browser.process?.()?.kill('SIGKILL');
+                            fs.unlinkSync(screenshotPath);
                         }
-                        catch { /* exact owned browser only */ }
+                        catch { /* proof is invalid when cleanup is incomplete */ }
+                        result = {
+                            captured: false,
+                            error: redactSensitiveText(`browser profile cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`),
+                        };
                     }
                 }
-                this.releaseTemp(browserProfile);
             }
-            return { captured: true };
-        }
-        catch (error) {
-            return { captured: false, error: redactSensitiveText(error instanceof Error ? error.message : String(error)) };
         }
+        return result;
     }
 }
+/** @deprecated Internal compatibility alias retained for older deep imports. */
+export { SystemBrowserScreenshotAdapter as OptionalPuppeteerScreenshotAdapter };

package/dist/utils/runtime-capability.d.ts

@@ -6,3 +6,10 @@ export type RuntimeCapabilities = {
 export declare function resolveRuntimeCapabilities(environment?: NodeJS.ProcessEnv): RuntimeCapabilities;
 export declare function hasLoopbackServiceCapability(environment?: NodeJS.ProcessEnv): boolean;
 export declare function hasLocalV3AgentCapability(environment?: NodeJS.ProcessEnv): boolean;
+/**
+ * An internal V3 service key may replace a user session only for an Agent
+ * request deliberately pinned to the local V3 service. Requiring both grants
+ * prevents a key present on an ecosystem host from bypassing unrelated
+ * user-session policies.
+ */
+export declare function hasLocalV3ServiceIdentity(environment?: NodeJS.ProcessEnv): boolean;

package/dist/utils/runtime-capability.js

@@ -14,3 +14,14 @@ export function hasLoopbackServiceCapability(environment = process.env) {
 export function hasLocalV3AgentCapability(environment = process.env) {
     return resolveRuntimeCapabilities(environment).localV3Agent;
 }
+/**
+ * An internal V3 service key may replace a user session only for an Agent
+ * request deliberately pinned to the local V3 service. Requiring both grants
+ * prevents a key present on an ecosystem host from bypassing unrelated
+ * user-session policies.
+ */
+export function hasLocalV3ServiceIdentity(environment = process.env) {
+    return hasLocalV3AgentCapability(environment) && Boolean(environment.VIGTHORIA_V3_SERVICE_KEY
+        || environment.V3_SERVICE_KEY
+        || environment.HYPERLOOP_SERVICE_KEY);
+}

package/dist/utils/runtime-temp.d.ts

@@ -49,6 +49,7 @@ export declare class RuntimeTempManager {
     private readonly source;
     private readonly maxBytes;
     private readonly minimumFreeBytes;
+    private readonly allocationMaxBytes;
     private readonly ttlMs;
     private initializedRoot;
     private initializedIdentity;
@@ -56,7 +57,7 @@ export declare class RuntimeTempManager {
     private lastCleanup;
     constructor(options?: RuntimeTempOptions);
     initialize(): RuntimeTempStatus;
-    createDirectory(prefix?: string): string;
+    createDirectory(prefix?: string, requestedMaxBytes?: number): string;
     removeDirectory(directory: string): void;
     scavenge(options?: {
         includeLegacy?: boolean;
@@ -68,10 +69,12 @@ export declare class RuntimeTempManager {
     private freeBytes;
     private measure;
     private removeEntry;
+    private acquireLock;
+    private releaseLock;
     private cleanupLegacySystemTemp;
 }
 export declare function getRuntimeTempManager(): RuntimeTempManager;
 export declare function initializeRuntimeTempStorage(): RuntimeTempStatus;
 export declare function runtimeTempStatus(): RuntimeTempStatus;
-export declare function createRuntimeTempDirectory(prefix: string): string;
+export declare function createRuntimeTempDirectory(prefix: string, requestedMaxBytes?: number): string;
 export declare function removeRuntimeTempDirectory(directory: string): void;