browser-debugger-cli 0.14.0 → 0.16.0

package/dist/telemetry/har/sanitize.js

@@ -0,0 +1,184 @@
+/**
+ * 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 { REDACTED, isSensitiveField, redactBase64Body, redactBody, redactOrReplaceWhole, redactPairs, } 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;
+/** {@link REDACTED} as base64, for a binary body or message replaced whole */
+const BASE64_REDACTED = Buffer.from(REDACTED).toString('base64');
+/** WebSocket opcode of a text message */
+const TEXT_OPCODE = 1;
+/** WebSocket opcode of a binary message (base64 in the HAR) */
+const BINARY_OPCODE = 2;
+/**
+ * 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, _webSocketMessages: messages } = 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: redactOrReplaceWhole(postData.text, (text) => redactBody(text, postData.mimeType)),
+                },
+            }),
+        },
+        response: {
+            ...response,
+            cookies: response.cookies.map(redactCookie),
+            headers: response.headers.map(redactHeader),
+            redirectURL: redactUrl(response.redirectURL),
+            content: redactContent(response.content),
+        },
+        ...(messages && { _webSocketMessages: messages.map(redactWebSocketMessage) }),
+    };
+}
+/**
+ * Redact credential fields of a response body, also of a base64 body whose
+ * type is generic or JSON.
+ *
+ * @param content - HAR response content
+ * @returns The content, or a copy with its text redacted; `size` stays as captured
+ */
+function redactContent(content) {
+    const { text, mimeType } = content;
+    if (text === undefined)
+        return content;
+    const redacted = content.encoding === 'base64'
+        ? redactOrReplaceWhole(text, (body) => redactBase64Body(body, mimeType), BASE64_REDACTED)
+        : redactOrReplaceWhole(text, (body) => redactBody(body, mimeType));
+    return redacted === text ? content : { ...content, text: redacted };
+}
+/**
+ * Redact credential fields of a WebSocket message: a text message, or a
+ * binary one that decodes as UTF-8 (redacted and encoded again).
+ *
+ * @param message - HAR WebSocket message
+ * @returns The message, or a copy with its data redacted
+ */
+function redactWebSocketMessage(message) {
+    if (message.opcode !== TEXT_OPCODE && message.opcode !== BINARY_OPCODE)
+        return message;
+    const data = message.opcode === TEXT_OPCODE
+        ? redactOrReplaceWhole(message.data, (text) => redactBody(text, ''))
+        : redactOrReplaceWhole(message.data, (text) => redactBase64Body(text, ''), BASE64_REDACTED);
+    return data === message.data ? message : { ...message, data };
+}
+/**
+ * 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,78 @@
+/**
+ * Credential redaction in request and response bodies, WebSocket text
+ * messages 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.
+ *
+ * JSON is never parsed and re-serialized: a single linear scan replaces the
+ * credential values in place, so everything else (64-bit numbers, formatting,
+ * duplicate keys, a BOM or `)]}'` prefix) stays byte for byte, and truncated
+ * JSON, socket.io and SockJS packets, server-sent events, NDJSON and JSON
+ * encoded in string values are covered too. JWTs are redacted under any name.
+ *
+ * Only JSON syntax is understood: single-quoted strings, unquoted keys,
+ * JSONP and `name:value` header lines (STOMP `passcode:`) are not.
+ */
+/** 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;
+/**
+ * Run a redaction, replacing the whole text when it fails, so that a body
+ * the sanitizer cannot handle is never exported as captured.
+ *
+ * @param text - Body or message text
+ * @param redact - Redaction of the text
+ * @param whole - Text written when the redaction throws
+ * @returns Redacted text, or `whole`
+ */
+export declare function redactOrReplaceWhole(text: string, redact: (text: string) => string, whole?: string): string;
+/**
+ * Replace every whole JWT (`eyJ` and three base64url segments, not part of a
+ * longer word) in text. Scanned by hand: a regular expression overflows the
+ * stack on a word of millions of characters.
+ *
+ * @param text - Text
+ * @param replacement - Text written instead of each JWT
+ * @returns Text with JWTs replaced; the text unchanged when it has none
+ */
+export declare function redactJwts(text: string, replacement: string): string;
+/**
+ * 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 body or WebSocket text message: 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 (empty for a WebSocket message)
+ * @returns Body with credential values replaced; the text unchanged when
+ *   there were none or it is neither JSON, a form nor multipart
+ */
+export declare function redactBody(text: string, mimeType: string): string;
+/**
+ * Redact credential fields of a base64 body or binary WebSocket message that
+ * may be text: one with no, a generic binary, a JSON, a form or an
+ * event-stream Content-Type that decodes as UTF-8.
+ *
+ * @param base64 - Body as base64
+ * @param mimeType - Content-Type of the body
+ * @returns The redacted body re-encoded, or the input unchanged when it was
+ *   not decodable text or held no credentials
+ */
+export declare function redactBase64Body(base64: string, mimeType: string): string;
+//# sourceMappingURL=sanitizeBody.d.ts.map