browser-debugger-cli 0.14.0 → 0.15.0

package/dist/telemetry/har/sanitize.js

@@ -0,0 +1,138 @@
+/**
+ * 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 bodies
+ * (sanitizeBody.ts). `headersSize` and `bodySize` stay those of the captured
+ * request. Response bodies and WebSocket messages are not redacted.
+ */
+import { REDACTED, isSensitiveField, redactPairs, redactRequestBody, } from './sanitizeBody.js';
+/** {@link REDACTED} as written in a URL */
+const URL_REDACTED = encodeURIComponent(REDACTED);
+/** Headers whose values are credentials, lowercased (others match by pattern) */
+const SENSITIVE_HEADERS = new Set([
+    'authorization',
+    'proxy-authorization',
+    'authentication',
+    'cookie',
+    'set-cookie',
+]);
+/** Custom headers carrying keys or tokens (`X-Api-Key`, `X-Auth-Token`, `X-CSRF-Token`) */
+const SENSITIVE_CUSTOM_HEADER = /^x-.*(key|token|secret|auth)/i;
+/**
+ * Headers with a credential segment between hyphens (`api-key`,
+ * `private-token`, `cf-access-jwt-assertion`, `ocp-apim-subscription-key`,
+ * `session-id`); `www-authenticate` and `proxy-authenticate` do not match
+ */
+const SENSITIVE_HEADER_SEGMENT = /(^|-)(api-?key|apikey|token|secret|jwt|subscription-key|session(-?id)?)(-|$)/i;
+/** Headers whose values are URLs that may carry credential parameters */
+const URL_HEADERS = new Set(['location', 'referer']);
+/** Query parameter names that hold credentials in URLs only (OAuth codes, signed URLs, API keys) */
+const SENSITIVE_URL_PARAM = /^(code|sig|key)$/i;
+/**
+ * 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 function sanitizeEntry(entry) {
+    const { request, response } = entry;
+    const postData = request.postData;
+    return {
+        ...entry,
+        request: {
+            ...request,
+            url: redactUrl(request.url),
+            cookies: request.cookies.map(redactCookie),
+            headers: request.headers.map(redactHeader),
+            queryString: request.queryString.map(redactQueryParam),
+            ...(postData?.text !== undefined && {
+                postData: { ...postData, text: redactRequestBody(postData.text, postData.mimeType) },
+            }),
+        },
+        response: {
+            ...response,
+            cookies: response.cookies.map(redactCookie),
+            headers: response.headers.map(redactHeader),
+            redirectURL: redactUrl(response.redirectURL),
+        },
+    };
+}
+/**
+ * Whether a header carries a credential.
+ *
+ * @param name - Header name (any case)
+ * @returns True for auth, cookie, API key, token, secret and session headers
+ */
+function isSensitiveHeader(name) {
+    return (SENSITIVE_HEADERS.has(name.toLowerCase()) ||
+        SENSITIVE_CUSTOM_HEADER.test(name) ||
+        SENSITIVE_HEADER_SEGMENT.test(name));
+}
+/**
+ * Redact a header's value if it carries a credential, or the credential
+ * parameters of a `Location` or `Referer` URL.
+ *
+ * @param header - HAR header
+ * @returns The header, or a copy with its value redacted
+ */
+function redactHeader(header) {
+    if (isSensitiveHeader(header.name))
+        return { ...header, value: REDACTED };
+    if (!URL_HEADERS.has(header.name.toLowerCase()))
+        return header;
+    const value = redactUrl(header.value);
+    return value === header.value ? header : { ...header, value };
+}
+/**
+ * Redact a cookie's value, keeping its name and attributes.
+ *
+ * @param cookie - HAR cookie
+ * @returns Copy with the value redacted
+ */
+function redactCookie(cookie) {
+    return { ...cookie, value: REDACTED };
+}
+/**
+ * Whether a URL query or fragment parameter holds a credential.
+ *
+ * @param name - Decoded parameter name
+ * @returns True for credential field names, `code`, `sig` and `key`
+ */
+function isSensitiveParam(name) {
+    return isSensitiveField(name) || SENSITIVE_URL_PARAM.test(name);
+}
+/**
+ * Redact a parsed query parameter if it holds a credential.
+ *
+ * @param param - HAR query parameter
+ * @returns The parameter, or a copy with its value redacted
+ */
+function redactQueryParam(param) {
+    return isSensitiveParam(param.name) ? { ...param, value: REDACTED } : param;
+}
+/**
+ * Redact credential parameter values in a URL's query and fragment
+ * (`#access_token=` of the OAuth implicit flow), leaving the rest byte for byte.
+ *
+ * @param url - URL (empty for none)
+ * @returns URL with credential values replaced by the URL-encoded {@link REDACTED}
+ */
+function redactUrl(url) {
+    const hash = url.indexOf('#');
+    const beforeHash = hash === -1 ? url : url.slice(0, hash);
+    const fragment = hash === -1 ? '' : `#${redactPairs(url.slice(hash + 1), isSensitiveParam, URL_REDACTED)}`;
+    const question = beforeHash.indexOf('?');
+    if (question === -1)
+        return beforeHash + fragment;
+    const query = redactPairs(beforeHash.slice(question + 1), isSensitiveParam, URL_REDACTED);
+    return `${beforeHash.slice(0, question)}?${query}${fragment}`;
+}
+//# sourceMappingURL=sanitize.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Credential redaction in request bodies and `name=value` lists, for
+ * sanitized HAR exports (see sanitize.ts).
+ *
+ * Matching is by field name only, so it over-redacts: any primitive whose
+ * name looks like a credential (`tokenCount: 5`) is replaced too.
+ */
+/** Replaces a credential value */
+export declare const REDACTED = "[redacted]";
+/**
+ * Whether a body field, form field or query parameter name looks like it
+ * holds a credential.
+ *
+ * @param name - Field name
+ * @returns True for password, token, secret, key, session and signature names
+ */
+export declare function isSensitiveField(name: string): boolean;
+/**
+ * Redact credential values in an `&`-separated `name=value` list (a form body,
+ * query string or fragment), leaving the other pairs byte for byte.
+ *
+ * @param text - List like `user=ann&password=hunter2`
+ * @param isSensitive - Whether a decoded name holds a credential
+ * @param replacement - Value written instead
+ * @returns List with credential values replaced
+ */
+export declare function redactPairs(text: string, isSensitive: (name: string) => boolean, replacement: string): string;
+/**
+ * Redact credential fields of a request body: multipart parts, form fields
+ * (by Content-Type or shape) and JSON fields at any depth.
+ *
+ * @param text - Body text
+ * @param mimeType - Content-Type of the body
+ * @returns Body with credential values replaced; the text unchanged when
+ *   there were none
+ */
+export declare function redactRequestBody(text: string, mimeType: string): string;
+//# sourceMappingURL=sanitizeBody.d.ts.map

package/dist/telemetry/har/sanitizeBody.js

@@ -0,0 +1,168 @@
+/**
+ * Credential redaction in request bodies and `name=value` lists, for
+ * sanitized HAR exports (see sanitize.ts).
+ *
+ * Matching is by field name only, so it over-redacts: any primitive whose
+ * name looks like a credential (`tokenCount: 5`) is replaced too.
+ */
+import { SENSITIVE_NAME_SOURCE } from '../../runtime/dom/elementInfo.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('network');
+/** Replaces a credential value */
+export const REDACTED = '[redacted]';
+/**
+ * Field names holding credentials: password-like names (shared with form
+ * masking), tokens, secrets, keys, sessions, signatures and credentials
+ */
+const SENSITIVE_FIELD = new RegExp(`${SENSITIVE_NAME_SOURCE}|token|secret|api[-_]?key|authoriz|credential|jwt|private[-_]?key|access[-_]?key|session|signature`, 'i');
+/** A body that is a form whatever its Content-Type: `k=v&k=v`, no whitespace, not JSON */
+const FORM_BODY = /^[^\s=&{["]+=[^\s&]*(?:&[^\s=&]+=[^\s&]*)*$/;
+/**
+ * Whether a body field, form field or query parameter name looks like it
+ * holds a credential.
+ *
+ * @param name - Field name
+ * @returns True for password, token, secret, key, session and signature names
+ */
+export function isSensitiveField(name) {
+    return SENSITIVE_FIELD.test(name);
+}
+/**
+ * Redact credential values in an `&`-separated `name=value` list (a form body,
+ * query string or fragment), leaving the other pairs byte for byte.
+ *
+ * @param text - List like `user=ann&password=hunter2`
+ * @param isSensitive - Whether a decoded name holds a credential
+ * @param replacement - Value written instead
+ * @returns List with credential values replaced
+ */
+export function redactPairs(text, isSensitive, replacement) {
+    return text
+        .split('&')
+        .map((pair) => {
+        const eq = pair.indexOf('=');
+        if (eq === -1 || !isSensitive(decodeName(pair.slice(0, eq))))
+            return pair;
+        return `${pair.slice(0, eq)}=${replacement}`;
+    })
+        .join('&');
+}
+/**
+ * Redact credential fields of a request body: multipart parts, form fields
+ * (by Content-Type or shape) and JSON fields at any depth.
+ *
+ * @param text - Body text
+ * @param mimeType - Content-Type of the body
+ * @returns Body with credential values replaced; the text unchanged when
+ *   there were none
+ */
+export function redactRequestBody(text, mimeType) {
+    if (/multipart\/form-data/i.test(mimeType))
+        return redactMultipart(text, mimeType);
+    if (/x-www-form-urlencoded/i.test(mimeType) || FORM_BODY.test(text)) {
+        return redactPairs(text, isSensitiveField, REDACTED);
+    }
+    return redactJsonBody(text);
+}
+/**
+ * Decode a form or query name.
+ *
+ * @param name - Encoded name
+ * @returns Decoded name, or the raw name when it is not valid encoding
+ */
+function decodeName(name) {
+    try {
+        return decodeURIComponent(name.replace(/\+/g, ' '));
+    }
+    catch (error) {
+        log.debug(`Field name not decodable: ${getErrorMessage(error)}`);
+        return name;
+    }
+}
+/**
+ * Redact the values of credential parts of a multipart body, leaving the
+ * other parts byte for byte.
+ *
+ * @param text - Body text
+ * @param mimeType - Content-Type with the boundary
+ * @returns Body with credential part values replaced
+ */
+function redactMultipart(text, mimeType) {
+    const match = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(mimeType);
+    const boundary = match?.[1] ?? match?.[2];
+    if (!boundary)
+        return text;
+    const delimiter = `--${boundary}`;
+    return text.split(delimiter).map(redactPart).join(delimiter);
+}
+/**
+ * Redact the value of one multipart part if its name holds a credential.
+ *
+ * @param part - Text between two boundary delimiters
+ * @returns The part, or the part with its value replaced
+ */
+function redactPart(part) {
+    const headerEnd = part.indexOf('\r\n\r\n');
+    if (headerEnd === -1)
+        return part;
+    const name = /;\s*name="([^"]*)"/i.exec(part.slice(0, headerEnd))?.[1];
+    if (name === undefined || !isSensitiveField(name))
+        return part;
+    const valueEnd = part.endsWith('\r\n') ? part.length - 2 : part.length;
+    return `${part.slice(0, headerEnd + 4)}${REDACTED}${part.slice(valueEnd)}`;
+}
+/**
+ * Redact credential fields of a JSON body.
+ *
+ * @param text - Body text
+ * @returns Re-serialized JSON when a field was redacted, the text unchanged
+ *   when none was or it is not JSON, and {@link REDACTED} for JSON too deep
+ *   to walk
+ */
+function redactJsonBody(text) {
+    if (!/^\s*[[{]/.test(text))
+        return text;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        log.debug(`Request body not JSON: ${getErrorMessage(error)}`);
+        return error instanceof SyntaxError ? text : REDACTED;
+    }
+    try {
+        const hits = { count: 0 };
+        const redacted = redactJson(parsed, false, hits);
+        return hits.count > 0 ? JSON.stringify(redacted) : text;
+    }
+    catch (error) {
+        log.debug(`Request body redacted whole: ${getErrorMessage(error)}`);
+        return REDACTED;
+    }
+}
+/**
+ * Copy of parsed JSON with the primitives under credential names replaced.
+ * Objects and arrays keep their structure; every string, number and boolean
+ * inside a credential-named field is replaced, at any depth.
+ *
+ * @param value - Parsed JSON value
+ * @param sensitive - Whether an enclosing field name holds a credential
+ * @param hits - Counter of replaced values
+ * @returns Redacted copy
+ */
+function redactJson(value, sensitive, hits) {
+    if (Array.isArray(value))
+        return value.map((item) => redactJson(item, sensitive, hits));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, field]) => [
+            key,
+            redactJson(field, sensitive || isSensitiveField(key), hits),
+        ]));
+    }
+    if (!sensitive || !['string', 'number', 'boolean'].includes(typeof value))
+        return value;
+    hits.count++;
+    return REDACTED;
+}
+//# sourceMappingURL=sanitizeBody.js.map

package/dist/ui/formatters/sessions.d.ts

@@ -1,7 +1,8 @@
 import type { RunningSessionInfo } from '../../session/sessionList.js';
 /**
- * Format the sessions as a table, followed by why ended sessions ended and
- * the cleanup commands of crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended, why
+ * untrusted sessions' directories are not safe to use, and the cleanup
+ * commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list

package/dist/ui/formatters/sessions.js

@@ -1,10 +1,11 @@
 import { OutputFormatter } from '../formatting.js';
-import { endedSessionText } from '../messages/session.js';
+import { endedSessionText, untrustedSessionText } from '../messages/session.js';
 /** Label of the default session in the list */
 const DEFAULT_SESSION_LABEL = '(default)';
 /**
- * Format the sessions as a table, followed by why ended sessions ended and
- * the cleanup commands of crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended, why
+ * untrusted sessions' directories are not safe to use, and the cleanup
+ * commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list
@@ -38,6 +39,12 @@ export function formatSessionList(data) {
     if (ended.length > 0) {
         fmt.blank().section('Ended without bdg stop:', ended);
     }
+    const untrusted = data.sessions.flatMap(({ name, untrusted: why }) => why ? [untrustedSessionText(name ?? DEFAULT_SESSION_LABEL, why)] : []);
+    if (untrusted.length > 0) {
+        fmt
+            .blank()
+            .section('Directory not safe to use (not asked; bdg status --session <name> says how to fix it):', untrusted);
+    }
     const cleanups = data.sessions.flatMap((session) => (session.cleanup ? [session.cleanup] : []));
     if (cleanups.length > 0) {
         fmt.hints('Crashed or stale sessions; clean up with:', cleanups);

package/dist/ui/messages/chrome.d.ts

@@ -20,8 +20,12 @@ export declare function formatChromeNotice(notice: NoticeDetails<ChromeNoticeCod
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export declare function formatChromeIssue(issue: IssueDetails): string;
+export declare function formatChromeIssue(issue: IssueDetails, diagnostics?: () => ChromeDiagnostics): string;
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -33,15 +37,19 @@ export declare function formatChromeIssue(issue: IssueDetails): string;
  */
 export declare function chromeExitedDuringStartupError(exitCode: number | null, output: string[], userDataDir: string, profileInUse: boolean): string;
 /**
- * Retrieve Chrome diagnostics and format for error messages.
- *
- * @returns Array of formatted diagnostic strings
+ * Options of {@link formatDiagnosticsForError}.
  */
-export declare function getFormattedDiagnostics(): string[];
+export interface DiagnosticsFormatOptions {
+    /** OS the CHROME_PATH example is for (default: this one) */
+    platform?: NodeJS.Platform;
+    /** Suggest CHROME_PATH when no Chrome is found (off when CHROME_PATH is the problem) */
+    suggestChromePath?: boolean;
+}
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -51,7 +59,7 @@ export declare function getFormattedDiagnostics(): string[];
  * console.error(errorLines.join('\n'));
  * ```
  */
-export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics): string[];
+export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics, { platform, suggestChromePath }?: DiagnosticsFormatOptions): string[];
 /**
  * Generate invalid port error message.
  *

package/dist/ui/messages/chrome.js

@@ -32,8 +32,12 @@ export function formatChromeNotice(notice) {
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export function formatChromeIssue(issue) {
+export function formatChromeIssue(issue, diagnostics = getChromeDiagnostics) {
     const ctx = issue.context ?? {};
     switch (issue.code) {
         case 'PORT_IN_USE':
@@ -52,16 +56,18 @@ export function formatChromeIssue(issue) {
                 : reason
                     ? chromeLaunchFailedError(reason)
                     : `Chrome failed to launch`;
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnostics, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
+            const found = diagnostics();
+            const diagnosticLines = formatDiagnosticsForError(found);
+            if (noChromeFound(found))
+                return joinLines(header, '', ...diagnosticLines);
+            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnosticLines, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
         }
         case 'CHROME_EXITED_DURING_STARTUP':
             return chromeExitedDuringStartupError(ctx['exitCode'], ctx['output'] ?? [], ctx['userDataDir'], ctx['profileInUse'] === true);
         case 'NO_PAGE_TARGET_FOUND':
             return noPageTargetFoundError(ctx['port'], ctx['availableTargets']);
         case 'CHROME_BINARY_NOT_FOUND': {
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...diagnostics);
+            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...formatDiagnosticsForError(diagnostics(), { suggestChromePath: false }));
         }
         case 'CHROME_BINARY_IS_DIRECTORY':
             return chromeBinaryOverrideIsDirectory(ctx['chromePath'], ctx['source']);
@@ -96,17 +102,49 @@ export function chromeExitedDuringStartupError(exitCode, output, userDataDir, pr
     return joinLines(`Chrome exited during startup (exit code ${exitCode ?? 'none'})`, ...(output.length > 0 ? ['Chrome said:', ...output.map((line) => `  ${line}`)] : []), 'Check --chrome-flags and BDG_CHROME_FLAGS (an unknown flag or value can stop Chrome)');
 }
 /**
- * Retrieve Chrome diagnostics and format for error messages.
+ * Whether no Chrome was found at all: no installation and no default binary
+ * (chrome-launcher's default honors a valid CHROME_PATH).
+ *
+ * @param diagnostics - Chrome diagnostics
+ * @returns True when there is nothing to launch
+ */
+function noChromeFound(diagnostics) {
+    return diagnostics.installationCount === 0 && !diagnostics.defaultPath;
+}
+/**
+ * A Chromium-based browser binary that chrome-launcher does not find on its
+ * own, as an example value for CHROME_PATH.
+ *
+ * @param platform - OS the path is for
+ * @returns Microsoft Edge's binary on macOS or Linux; none on other systems
+ */
+function exampleChromePath(platform) {
+    if (platform === 'darwin')
+        return '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
+    if (platform === 'linux')
+        return '/usr/bin/microsoft-edge';
+    return undefined;
+}
+/**
+ * How to point bdg at another Chromium-based browser through CHROME_PATH.
  *
- * @returns Array of formatted diagnostic strings
+ * @param platform - OS the example is for
+ * @returns Message lines, with an example command where one is known
  */
-export function getFormattedDiagnostics() {
-    return formatDiagnosticsForError(getChromeDiagnostics());
+function chromePathSuggestion(platform) {
+    const example = exampleChromePath(platform);
+    if (!example)
+        return ['Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium)\n'];
+    return [
+        'Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium), e.g.:',
+        `   CHROME_PATH="${example}" ${sessionCommand('bdg <url>')}\n`,
+    ];
 }
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -116,11 +154,13 @@ export function getFormattedDiagnostics() {
  * console.error(errorLines.join('\n'));
  * ```
  */
-export function formatDiagnosticsForError(diagnostics) {
+export function formatDiagnosticsForError(diagnostics, { platform = process.platform, suggestChromePath = true } = {}) {
     const lines = [];
-    if (diagnostics.installationCount === 0) {
+    if (noChromeFound(diagnostics)) {
         lines.push('Error: No Chrome installations detected\n');
-        lines.push('Install Chrome from:');
+        if (suggestChromePath)
+            lines.push(...chromePathSuggestion(platform));
+        lines.push(suggestChromePath ? 'Or install Chrome from:' : 'Install Chrome from:');
         lines.push('   https://www.google.com/chrome/\n');
     }
     else {

package/dist/ui/messages/networkMessages.d.ts

@@ -53,4 +53,30 @@ export declare function headerRepeatedNote(count: number): string;
  * @returns Note text
  */
 export declare function localProxyNote(): string;
+/**
+ * HAR log comment of a sanitized export.
+ *
+ * @returns Comment naming what was redacted and the flag that keeps it
+ */
+export declare function harSanitizedComment(): string;
+/**
+ * Result of a HAR export to a file.
+ */
+export interface HarExportSummary {
+    /** Absolute path written */
+    file: string;
+    /** Requests exported */
+    entries: number;
+    /** Whether --filter left requests out */
+    filtered: boolean;
+    /** Whether credentials were redacted */
+    sanitized: boolean;
+}
+/**
+ * Success message of `bdg network har`.
+ *
+ * @param result - Export result
+ * @returns e.g. `✓ Exported 4 requests to /tmp/out.har` and a line on sanitization
+ */
+export declare function harExportedMessage(result: HarExportSummary): string;
 //# sourceMappingURL=networkMessages.d.ts.map

package/dist/ui/messages/networkMessages.js

@@ -82,4 +82,25 @@ export function headerRepeatedNote(count) {
 export function localProxyNote() {
     return '(loopback; likely a local proxy)';
 }
+/**
+ * HAR log comment of a sanitized export.
+ *
+ * @returns Comment naming what was redacted and the flag that keeps it
+ */
+export function harSanitizedComment() {
+    return 'Sanitized by bdg: values of auth, cookie, API key, token and session headers, cookies, credential query parameters in URLs, and password/token fields of request bodies are [redacted] (by name, so some harmless values are too); response bodies and WebSocket messages are not sanitized. Export with --include-sensitive to keep everything';
+}
+/**
+ * Success message of `bdg network har`.
+ *
+ * @param result - Export result
+ * @returns e.g. `✓ Exported 4 requests to /tmp/out.har` and a line on sanitization
+ */
+export function harExportedMessage(result) {
+    const filterNote = result.filtered ? ' (filtered)' : '';
+    const note = result.sanitized
+        ? 'Credentials sanitized (auth/cookie/API key/token headers, cookies, URL tokens, password and token body fields are [redacted]); --include-sensitive keeps them'
+        : '⚠ Includes credentials (--include-sensitive): share this file with care';
+    return `✓ Exported ${result.entries} requests${filterNote} to ${result.file}\n  ${note}`;
+}
 //# sourceMappingURL=networkMessages.js.map

package/dist/ui/messages/session.d.ts

@@ -88,6 +88,14 @@ export declare function endedSessionText(label: string, end: {
     reason: string;
     endedAt: number;
 }): string;
+/**
+ * A session whose directory is not safe to use, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param why - Untrusted directory and why
+ * @returns One line
+ */
+export declare function untrustedSessionText(label: string, why: string): string;
 /**
  * Note after a failed start or a stop whose daemon had not exited when bdg stopped waiting.
  *

package/dist/ui/messages/session.js

@@ -101,6 +101,16 @@ export function lastSessionEndText(end) {
 export function endedSessionText(label, end) {
     return `${label} ended ${sessionEndText(end)}`;
 }
+/**
+ * A session whose directory is not safe to use, for `bdg sessions`.
+ *
+ * @param label - Session name as listed
+ * @param why - Untrusted directory and why
+ * @returns One line
+ */
+export function untrustedSessionText(label, why) {
+    return `${label}: ${why}`;
+}
 /**
  * When and why a session ended without `bdg stop`.
  *

package/dist/utils/atomicFile.d.ts

@@ -38,12 +38,13 @@ export declare class AtomicFileWriter {
      *
      * @param filePath - Target file path
      * @param data - Data to write
-     * @param options - Write options
+     * @param options - Write options (`mode`: permissions of the new file, less the umask)
      * @returns Promise that resolves when write completes
      * @throws Error if write operation fails
      */
     static writeAsync(filePath: string, data: string, options?: {
         encoding?: BufferEncoding;
+        mode?: number;
     }): Promise<void>;
     /**
      * Write binary data (Buffer) to a file atomically (asynchronous).

package/dist/utils/atomicFile.js

@@ -59,14 +59,17 @@ export class AtomicFileWriter {
      *
      * @param filePath - Target file path
      * @param data - Data to write
-     * @param options - Write options
+     * @param options - Write options (`mode`: permissions of the new file, less the umask)
      * @returns Promise that resolves when write completes
      * @throws Error if write operation fails
      */
     static async writeAsync(filePath, data, options = {}) {
         const tmpPath = this.getTempPath(filePath);
         try {
-            await fs.promises.writeFile(tmpPath, data, { encoding: options.encoding ?? 'utf-8' });
+            await fs.promises.writeFile(tmpPath, data, {
+                encoding: options.encoding ?? 'utf-8',
+                ...(options.mode !== undefined && { mode: options.mode }),
+            });
             await fs.promises.rename(tmpPath, filePath);
         }
         catch (error) {