browser-debugger-cli 0.14.0 → 0.16.0

package/dist/telemetry/downloads.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Download tracking: where a session's downloads go, and what became of them.
+ */
+import type { CDPConnection } from '../connection/cdp.js';
+import type { DownloadInfo } from '../ipc/protocol/domTypes.js';
+/** A download the session saw begin, with Chrome's id for it */
+export interface TrackedDownload extends DownloadInfo {
+    guid: string;
+}
+/**
+ * Where a session's downloads go: a directory bdg chose (a Chrome bdg
+ * launched), wherever the browser puts them (an attached Chrome), or nowhere
+ * (bdg's directory could not be created: refusing beats saving them to
+ * `~/Downloads`), with why
+ */
+export type DownloadDestination = {
+    kind: 'directory';
+    dir: string;
+} | {
+    kind: 'browser';
+} | {
+    kind: 'refused';
+    reason: string;
+};
+/** Paths chosen for downloads still running, by {@link reservationKey} */
+type Reservations = Set<string>;
+/** Where the session keeps its downloads and what it says about them */
+export interface DownloadRecord {
+    /** Downloads that began, oldest first, updated as they progress */
+    downloads: TrackedDownload[];
+    /** Set while downloads do not go where bdg meant them to (refused, or not redirected) */
+    downloadsWarning: string | undefined;
+}
+/**
+ * Track the session's downloads.
+ *
+ * In a directory, Chrome saves each download under its id (`allowAndName`),
+ * and the file is renamed to the suggested name once complete; the name is
+ * chosen when the download begins (`report (1).txt` when `report.txt` exists
+ * or was chosen for another), so a download still running already reports
+ * where it will be. In the browser's place, its own download settings stay
+ * and only its events are enabled. Refused downloads are canceled by Chrome
+ * and recorded with the reason.
+ *
+ * Chrome keeps a download behavior only while the connection that set it is
+ * open, so {@link attach} applies it again on another connection when the
+ * first one is lost. A browser-level connection also receives download
+ * events of other tabs (`target=_blank` links, `window.open()`), which do not
+ * reach a page's connection.
+ */
+export declare class DownloadTracker {
+    private readonly record;
+    private readonly destination;
+    private readonly reserved;
+    private applied;
+    private unsubscribe;
+    /** Set once stopped: no connection is followed, nor any behavior set, afterwards */
+    private stopped;
+    /** Number of the latest attach: an earlier one still running gives way to it */
+    private latestAttach;
+    /** Attaches run one after another */
+    private attaching;
+    /**
+     * @param record - Session record receiving downloads and the warning
+     * @param destination - Where downloads should go
+     */
+    constructor(record: DownloadRecord, destination: DownloadDestination);
+    /**
+     * Apply the destination on a connection and follow its download events
+     * there (instead of on the previous one). When Chrome refuses it, reports
+     * stop claiming bdg's directory (downloads go where the browser puts them)
+     * and the record carries a warning.
+     *
+     * Attaches run one at a time, and the latest wins: one called meanwhile
+     * (the browser-level connection lost while it was being set up) makes an
+     * earlier one give way without following its connection or warning. After
+     * {@link stop}, nothing is followed and no behavior is set.
+     *
+     * @param cdp - Connection (browser-level when possible)
+     * @returns True when Chrome took the destination on this connection
+     */
+    attach(cdp: CDPConnection): Promise<boolean>;
+    /** Stop following download events */
+    stop(): void;
+    /**
+     * Whether an attach was superseded by a later one or by {@link stop}.
+     *
+     * @param attempt - Number of the attach
+     * @returns True when it must give way
+     */
+    private superseded;
+    /**
+     * Set the behavior on a connection and follow its events, unless the
+     * attach was superseded before or while Chrome answered.
+     *
+     * @param cdp - Connection
+     * @param attempt - Number of the attach
+     * @returns True when Chrome took the destination and the attach still stands
+     */
+    private applyOn;
+    /**
+     * Record a download that began, with the path chosen for it in bdg's directory.
+     *
+     * @param event - `Browser.downloadWillBegin` parameters
+     */
+    private begin;
+}
+/**
+ * A tracked download as commands report it, as it is now.
+ *
+ * @param download - Tracked download
+ * @returns Copy without Chrome's id
+ */
+export declare function toDownloadInfo(download: TrackedDownload): DownloadInfo;
+/**
+ * Choose a free path for a download: its suggested name, or with ` (1)`,
+ * ` (2)`… before the extension when a file or another running download has
+ * that name.
+ *
+ * @param downloadDir - Directory downloads are saved into
+ * @param suggestedFilename - Name the page or server suggested
+ * @param reserved - Paths chosen for downloads still running (the result is added)
+ * @returns Absolute path
+ */
+export declare function reserveDownloadPath(downloadDir: string, suggestedFilename: string, reserved: Reservations): string;
+export {};
+//# sourceMappingURL=downloads.d.ts.map

package/dist/telemetry/downloads.js

@@ -0,0 +1,265 @@
+/**
+ * Download tracking: where a session's downloads go, and what became of them.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createLogger } from '../ui/logging/index.js';
+import { downloadsNotRedirectedWarning } from '../ui/messages/commands.js';
+import { getErrorMessage } from '../utils/errors.js';
+const log = createLogger('downloads');
+/** Name given to a download whose suggested name is not a usable file name */
+const FALLBACK_FILE_NAME = 'download';
+/**
+ * Track the session's downloads.
+ *
+ * In a directory, Chrome saves each download under its id (`allowAndName`),
+ * and the file is renamed to the suggested name once complete; the name is
+ * chosen when the download begins (`report (1).txt` when `report.txt` exists
+ * or was chosen for another), so a download still running already reports
+ * where it will be. In the browser's place, its own download settings stay
+ * and only its events are enabled. Refused downloads are canceled by Chrome
+ * and recorded with the reason.
+ *
+ * Chrome keeps a download behavior only while the connection that set it is
+ * open, so {@link attach} applies it again on another connection when the
+ * first one is lost. A browser-level connection also receives download
+ * events of other tabs (`target=_blank` links, `window.open()`), which do not
+ * reach a page's connection.
+ */
+export class DownloadTracker {
+    record;
+    destination;
+    reserved = new Set();
+    applied = { kind: 'browser' };
+    unsubscribe = () => undefined;
+    /** Set once stopped: no connection is followed, nor any behavior set, afterwards */
+    stopped = false;
+    /** Number of the latest attach: an earlier one still running gives way to it */
+    latestAttach = 0;
+    /** Attaches run one after another */
+    attaching = Promise.resolve();
+    /**
+     * @param record - Session record receiving downloads and the warning
+     * @param destination - Where downloads should go
+     */
+    constructor(record, destination) {
+        this.record = record;
+        this.destination = destination;
+        if (destination.kind === 'refused')
+            record.downloadsWarning = destination.reason;
+    }
+    /**
+     * Apply the destination on a connection and follow its download events
+     * there (instead of on the previous one). When Chrome refuses it, reports
+     * stop claiming bdg's directory (downloads go where the browser puts them)
+     * and the record carries a warning.
+     *
+     * Attaches run one at a time, and the latest wins: one called meanwhile
+     * (the browser-level connection lost while it was being set up) makes an
+     * earlier one give way without following its connection or warning. After
+     * {@link stop}, nothing is followed and no behavior is set.
+     *
+     * @param cdp - Connection (browser-level when possible)
+     * @returns True when Chrome took the destination on this connection
+     */
+    attach(cdp) {
+        const attempt = ++this.latestAttach;
+        const run = this.attaching.then(() => this.applyOn(cdp, attempt));
+        this.attaching = run.catch(() => undefined);
+        return run;
+    }
+    /** Stop following download events */
+    stop() {
+        this.stopped = true;
+        this.unsubscribe();
+    }
+    /**
+     * Whether an attach was superseded by a later one or by {@link stop}.
+     *
+     * @param attempt - Number of the attach
+     * @returns True when it must give way
+     */
+    superseded(attempt) {
+        return this.stopped || attempt !== this.latestAttach;
+    }
+    /**
+     * Set the behavior on a connection and follow its events, unless the
+     * attach was superseded before or while Chrome answered.
+     *
+     * @param cdp - Connection
+     * @param attempt - Number of the attach
+     * @returns True when Chrome took the destination and the attach still stands
+     */
+    async applyOn(cdp, attempt) {
+        if (this.superseded(attempt))
+            return false;
+        this.unsubscribe();
+        const error = await setDownloadBehavior(cdp, this.destination);
+        if (this.superseded(attempt))
+            return false;
+        this.applied = error === undefined ? this.destination : { kind: 'browser' };
+        if (this.destination.kind === 'directory') {
+            this.record.downloadsWarning =
+                error === undefined ? undefined : downloadsNotRedirectedWarning(error);
+        }
+        const handlers = [
+            cdp.on('Browser.downloadWillBegin', (event) => this.begin(event)),
+            cdp.on('Browser.downloadProgress', (progress) => {
+                const download = this.record.downloads.findLast((entry) => entry.guid === progress.guid);
+                if (download?.state !== 'inProgress')
+                    return;
+                updateDownload(download, progress, this.applied, this.reserved);
+            }),
+        ];
+        this.unsubscribe = () => handlers.forEach((remove) => remove());
+        return error === undefined;
+    }
+    /**
+     * Record a download that began, with the path chosen for it in bdg's directory.
+     *
+     * @param event - `Browser.downloadWillBegin` parameters
+     */
+    begin({ guid, url, suggestedFilename }) {
+        const dir = this.applied.kind === 'directory' ? this.applied.dir : undefined;
+        const target = dir && reserveDownloadPath(dir, suggestedFilename, this.reserved);
+        this.record.downloads.push({
+            guid,
+            url,
+            suggestedFilename,
+            state: 'inProgress',
+            ...(target && { path: target }),
+        });
+    }
+}
+/**
+ * A tracked download as commands report it, as it is now.
+ *
+ * @param download - Tracked download
+ * @returns Copy without Chrome's id
+ */
+export function toDownloadInfo(download) {
+    const { url, suggestedFilename, path: file, state, bytes, reason } = download;
+    return {
+        url,
+        suggestedFilename,
+        ...(file !== undefined && { path: file }),
+        state,
+        ...(bytes !== undefined && { bytes }),
+        ...(reason !== undefined && { reason }),
+    };
+}
+/**
+ * Set the browser's download behavior for the destination and enable
+ * download events.
+ *
+ * @param cdp - CDP connection
+ * @param destination - Where downloads go
+ * @returns Why Chrome refused it, or undefined when it took it
+ */
+async function setDownloadBehavior(cdp, destination) {
+    const behavior = destination.kind === 'directory'
+        ? { behavior: 'allowAndName', downloadPath: destination.dir }
+        : { behavior: destination.kind === 'refused' ? 'deny' : 'default' };
+    try {
+        await cdp.send('Browser.setDownloadBehavior', { ...behavior, eventsEnabled: true });
+        return undefined;
+    }
+    catch (error) {
+        log.info(`Download behavior not set: ${getErrorMessage(error)}`);
+        return getErrorMessage(error);
+    }
+}
+/**
+ * Apply a progress event: bytes so far, then the final state; a completed
+ * download in bdg's directory is renamed from its id to its chosen name.
+ *
+ * @param download - Download being updated
+ * @param progress - Progress event
+ * @param destination - Where downloads go
+ * @param reserved - Paths chosen for downloads still running
+ */
+function updateDownload(download, progress, destination, reserved) {
+    download.bytes = progress.receivedBytes;
+    if (progress.state === 'inProgress')
+        return;
+    if (download.path)
+        reserved.delete(reservationKey(download.path));
+    if (progress.state === 'canceled') {
+        delete download.path;
+        if (destination.kind === 'refused')
+            download.reason = destination.reason;
+    }
+    else if (destination.kind === 'directory') {
+        download.path = saveUnderChosenName(destination.dir, download, reserved);
+    }
+    else if (progress.filePath) {
+        download.path = progress.filePath;
+    }
+    download.state = progress.state;
+}
+/**
+ * Rename a completed download from its id to the name chosen for it (another
+ * one when a file took that name meanwhile).
+ *
+ * @param downloadDir - Directory downloads are saved into
+ * @param download - Completed download
+ * @param reserved - Paths chosen for downloads still running
+ * @returns Path of the file: the chosen one, or its id's when renaming failed
+ */
+function saveUnderChosenName(downloadDir, download, reserved) {
+    const saved = path.join(downloadDir, download.guid);
+    const chosen = download.path && !fs.existsSync(download.path)
+        ? download.path
+        : reserveDownloadPath(downloadDir, download.suggestedFilename, reserved);
+    reserved.delete(reservationKey(chosen));
+    try {
+        fs.renameSync(saved, chosen);
+        return chosen;
+    }
+    catch (error) {
+        log.debug(`Download ${download.guid} kept under its id: ${getErrorMessage(error)}`);
+        return saved;
+    }
+}
+/**
+ * Key of a reserved path: lowercased, so `Report.txt` and `report.txt` do not
+ * both get chosen on a case-insensitive file system (macOS, Windows).
+ *
+ * @param file - Path
+ * @returns Key
+ */
+function reservationKey(file) {
+    return file.toLowerCase();
+}
+/**
+ * Choose a free path for a download: its suggested name, or with ` (1)`,
+ * ` (2)`… before the extension when a file or another running download has
+ * that name.
+ *
+ * @param downloadDir - Directory downloads are saved into
+ * @param suggestedFilename - Name the page or server suggested
+ * @param reserved - Paths chosen for downloads still running (the result is added)
+ * @returns Absolute path
+ */
+export function reserveDownloadPath(downloadDir, suggestedFilename, reserved) {
+    const name = safeFileName(suggestedFilename);
+    const { name: stem, ext } = path.parse(name);
+    for (let copy = 0;; copy++) {
+        const candidate = path.join(downloadDir, copy === 0 ? name : `${stem} (${copy})${ext}`);
+        if (reserved.has(reservationKey(candidate)) || fs.existsSync(candidate))
+            continue;
+        reserved.add(reservationKey(candidate));
+        return candidate;
+    }
+}
+/**
+ * A suggested file name reduced to a name in the download directory.
+ *
+ * @param suggestedFilename - Name the page or server suggested
+ * @returns Its last path segment, or {@link FALLBACK_FILE_NAME} when that is empty, `.` or `..`
+ */
+function safeFileName(suggestedFilename) {
+    const name = path.basename(suggestedFilename.replaceAll('\\', '/'));
+    return name === '' || name === '.' || name === '..' ? FALLBACK_FILE_NAME : name;
+}
+//# sourceMappingURL=downloads.js.map

package/dist/telemetry/har/builder.d.ts

@@ -18,11 +18,22 @@ export interface HARMetadata {
     /** Target title (optional) */
     targetTitle?: string;
 }
+/**
+ * Options for HAR generation.
+ */
+export interface HAROptions {
+    /** Keep credentials as captured instead of redacting them (see sanitize.ts) */
+    includeSensitive?: boolean;
+}
 /**
  * Build HAR 1.2 format from network telemetry data.
  *
+ * Credentials are redacted (`log.comment` says so) unless
+ * `options.includeSensitive` is set.
+ *
  * @param requests - Array of network requests collected during session
  * @param metadata - Metadata for HAR creator/browser info
+ * @param options - Whether to keep credentials
  * @returns Complete HAR object
  *
  * @remarks
@@ -39,5 +50,5 @@ export interface HARMetadata {
  * fs.writeFileSync('capture.har', JSON.stringify(har, null, 2));
  * ```
  */
-export declare function buildHAR(requests: NetworkRequest[], metadata: HARMetadata): HAR;
+export declare function buildHAR(requests: NetworkRequest[], metadata: HARMetadata, options?: HAROptions): HAR;
 //# sourceMappingURL=builder.d.ts.map

package/dist/telemetry/har/builder.js

@@ -2,7 +2,9 @@
  * HAR (HTTP Archive) builder for transforming network telemetry to HAR 1.2 format.
  */
 import { createRequire } from 'node:module';
+import { sanitizeEntry } from './sanitize.js';
 import { skippedBodyReason } from '../networkRetention.js';
+import { harSanitizedComment } from '../../ui/messages/networkMessages.js';
 /**
  * Loads Node builtins on first use: importing `node:http` in an ES module
  * reads all its exports, which loads undici and zlib (about 8 ms of every CLI
@@ -14,8 +16,12 @@ const DEFAULT_HTTP_VERSION = 'HTTP/1.1';
 /**
  * Build HAR 1.2 format from network telemetry data.
  *
+ * Credentials are redacted (`log.comment` says so) unless
+ * `options.includeSensitive` is set.
+ *
  * @param requests - Array of network requests collected during session
  * @param metadata - Metadata for HAR creator/browser info
+ * @param options - Whether to keep credentials
  * @returns Complete HAR object
  *
  * @remarks
@@ -32,8 +38,9 @@ const DEFAULT_HTTP_VERSION = 'HTTP/1.1';
  * fs.writeFileSync('capture.har', JSON.stringify(har, null, 2));
  * ```
  */
-export function buildHAR(requests, metadata) {
-    const entries = [...requests].sort((a, b) => a.timestamp - b.timestamp).map(buildEntry);
+export function buildHAR(requests, metadata, options = {}) {
+    const built = [...requests].sort((a, b) => a.timestamp - b.timestamp).map(buildEntry);
+    const entries = options.includeSensitive ? built : built.map(sanitizeEntry);
     const log = {
         version: '1.2',
         creator: {
@@ -42,6 +49,7 @@ export function buildHAR(requests, metadata) {
             comment: 'Browser Debugger CLI - https://github.com/szymdzum/browser-debugger-cli',
         },
         entries,
+        ...(!options.includeSensitive && { comment: harSanitizedComment() }),
     };
     if (metadata.chromeVersion) {
         log.browser = {
@@ -93,6 +101,7 @@ function buildWebSocketMessage(frame) {
         time: frame.timestamp / 1000,
         opcode: frame.opcode,
         data: frame.payloadData,
+        ...(frame.truncatedFrom !== undefined && { _truncatedFrom: frame.truncatedFrom }),
     };
 }
 /**
@@ -111,7 +120,7 @@ function buildRequest(req) {
         headers: convertHeaders(req.requestHeaders),
         queryString: extractQueryParams(url),
         headersSize: estimateRequestHeadersSize(req.method, req.url, req.requestHeaders),
-        bodySize: req.requestBody ? Buffer.byteLength(req.requestBody, 'utf-8') : 0,
+        bodySize: requestBodySize(req),
     };
     const postData = buildPostData(req);
     if (postData) {
@@ -181,7 +190,21 @@ function contentLength(req) {
     return Number.isInteger(bytes) && bytes >= 0 ? bytes : undefined;
 }
 /**
- * Build POST data object if request has body.
+ * Size of the request body: unknown (-1) when it was evicted at the body budget.
+ *
+ * @param req - Network request data
+ * @returns Body size in bytes, or -1
+ */
+function requestBodySize(req) {
+    if (!req.requestBody)
+        return 0;
+    if (skippedBodyReason(req.requestBody) !== undefined)
+        return -1;
+    return Buffer.byteLength(req.requestBody, 'utf-8');
+}
+/**
+ * Build POST data object if request has body. A body bdg did not keep is
+ * exported without `text` and with the reason as `comment`.
  *
  * @param req - Network request data
  * @returns POST data object or undefined
@@ -189,11 +212,11 @@ function contentLength(req) {
 function buildPostData(req) {
     if (!req.requestBody)
         return undefined;
-    const contentType = getHeader(req.requestHeaders, 'content-type') ?? 'text/plain';
-    return {
-        mimeType: contentType,
-        text: req.requestBody,
-    };
+    const mimeType = getHeader(req.requestHeaders, 'content-type') ?? 'text/plain';
+    const skipped = skippedBodyReason(req.requestBody);
+    if (skipped !== undefined)
+        return { mimeType, comment: `Body not captured: ${skipped}` };
+    return { mimeType, text: req.requestBody };
 }
 /**
  * Duration between two CDP timing offsets (ms), or -1 if either is unknown.

package/dist/telemetry/har/sanitize.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Credential redaction for HAR exports.
+ *
+ * HAR files are made to be shared (bug reports, tickets), so `bdg network har`
+ * redacts credentials by default, as Chrome DevTools does since Chrome 130.
+ * Chrome's sanitized export drops the `Cookie`, `Set-Cookie` and
+ * `Authorization` headers and empties the `cookies` arrays; bdg instead keeps
+ * every header, cookie and parameter name (and cookie attributes such as
+ * `httpOnly`) with the value `[redacted]`, so the export still shows that a
+ * request was authenticated and which cookies were set. It also covers API
+ * key, token and session headers, credential query parameters in URLs
+ * (`?code=`, `?access_token=`), and credential fields of request and response
+ * bodies and of WebSocket text messages (sanitizeBody.ts), editing only
+ * those values. `headersSize`, `bodySize` and `content.size` stay those of the
+ * captured request. Base64 bodies are decoded when their type is generic,
+ * JSON, form or event-stream, and binary WebSocket messages always; those
+ * that are not UTF-8 text, and other binary bodies, are kept. A body or
+ * message the sanitizer fails on is replaced whole by {@link REDACTED}.
+ */
+import type { Entry } from './types.js';
+/**
+ * Redact the credentials of a HAR entry.
+ *
+ * @param entry - Entry built from the captured request
+ * @returns Copy of the entry with credential values replaced by {@link REDACTED}
+ */
+export declare function sanitizeEntry(entry: Entry): Entry;
+//# sourceMappingURL=sanitize.d.ts.map