@scalebun-release/react-native 2.5.0

package/src/integrations/network/bodyCapture.ts

@@ -0,0 +1,328 @@
+/**
+ * ScaleBun SDK — Network Body & Header Capture Helpers
+ *
+ * Pure, no-throw utilities shared by both the fetch and XHR interceptors.
+ *
+ * ⚠️  PRIVACY: These helpers capture raw HTTP payload content.
+ * They MUST only be called when `captureNetworkBodies` is explicitly
+ * enabled by the integrator. The integrator is responsible for ensuring
+ * compliance with applicable privacy laws (GDPR, CCPA, etc.).
+ *
+ * Redaction is applied by the caller via `redactHeaders` / `redactBody` /
+ * `redactNetworkEvent` from `src/debug/redaction.ts`.
+ *
+ * Scope: JS-host only (fetch / XHR).
+ * Native-layer capture (OkHttp, URLSession) is future work.
+ */
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const DEFAULT_BODY_MAX_BYTES = 65_536; // 64 KiB
+
+/**
+ * Content-type prefixes for non-textual responses that should be skipped.
+ * Capturing binary bodies would produce unreadable noise in the desktop panel.
+ */
+const BINARY_CONTENT_TYPES = [
+    'image/',
+    'audio/',
+    'video/',
+    'application/octet-stream',
+    'application/zip',
+    'application/gzip',
+    'application/pdf',
+    'font/',
+];
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Marker emitted when a body cannot be read synchronously (FormData, stream). */
+export interface UnreadableBody {
+    kind: 'unreadable';
+    reason: 'FormData' | 'ReadableStream' | 'Blob' | 'ArrayBuffer' | 'unknown';
+}
+
+/** Marker emitted when a body is truncated to fit the byte cap. */
+export interface TruncatedBody {
+    kind: 'truncated';
+    preview: string;
+    totalBytes: number;
+    capturedBytes: number;
+}
+
+/** Marker emitted when the content-type indicates binary/non-textual content. */
+export interface SkippedBody {
+    kind: 'skipped';
+    reason: 'binary-content-type';
+    contentType: string;
+}
+
+export type CapturedBody =
+    | string
+    | object
+    | null
+    | UnreadableBody
+    | TruncatedBody
+    | SkippedBody;
+
+// ─── Content-Type Guard ───────────────────────────────────────────────────────
+
+/**
+ * Returns true when the content-type indicates binary/non-textual content
+ * that should be skipped rather than captured.
+ * Never throws.
+ */
+export function isBinaryContentType(contentType: string | null | undefined): boolean {
+    if (!contentType) return false;
+    const lower = contentType.toLowerCase();
+    return BINARY_CONTENT_TYPES.some(prefix => lower.startsWith(prefix));
+}
+
+// ─── Size Helpers (non-PII byte counts) ───────────────────────────────────────
+//
+// Byte *counts* carry no payload content, so — unlike body/header capture — they
+// are safe to compute unconditionally (independent of `captureNetworkBodies`).
+// They feed the request/response size columns the dashboard network drawer shows.
+
+/** UTF-8 byte length of a string. Never throws. */
+export function utf8ByteLength(s: string): number {
+    try {
+        if (typeof Buffer !== 'undefined') return Buffer.byteLength(s, 'utf8');
+        // Fallback without TextEncoder: count UTF-8 bytes via URI encoding.
+        return unescape(encodeURIComponent(s)).length;
+    } catch {
+        return s.length;
+    }
+}
+
+/**
+ * Best-effort byte size of an outgoing request body, computed synchronously
+ * without consuming streams. Returns 0 when the size can't be known cheaply
+ * (FormData / Blob / stream). Never throws.
+ */
+export function requestBodyBytes(body: unknown): number {
+    try {
+        if (body === null || body === undefined) return 0;
+        if (typeof body === 'string') return utf8ByteLength(body);
+        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+            return utf8ByteLength(body.toString());
+        }
+        if (typeof Blob !== 'undefined' && body instanceof Blob) return body.size;
+        if (body instanceof ArrayBuffer) return body.byteLength;
+        if (ArrayBuffer.isView(body as any)) return (body as ArrayBufferView).byteLength;
+        return 0;
+    } catch {
+        return 0;
+    }
+}
+
+/** Parse a `content-length` header value to a byte count. 0 when absent/invalid. */
+export function contentLengthBytes(value: string | null | undefined): number {
+    if (!value) return 0;
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+// ─── Request Body Extraction ─────────────────────────────────────────────────
+
+/**
+ * Synchronously extract the request body from a fetch `init.body` value.
+ *
+ * - `string`         → returned as-is (already textual)
+ * - `URLSearchParams` → `.toString()` (safe, synchronous)
+ * - `FormData`       → `{ kind: 'unreadable', reason: 'FormData' }`
+ * - `ReadableStream` → `{ kind: 'unreadable', reason: 'ReadableStream' }`
+ * - `Blob`           → `{ kind: 'unreadable', reason: 'Blob' }`
+ * - `ArrayBuffer`    → `{ kind: 'unreadable', reason: 'ArrayBuffer' }`
+ * - null/undefined   → null
+ *
+ * Never throws.
+ */
+export function extractRequestBody(body: unknown): CapturedBody {
+    try {
+        if (body === null || body === undefined) return null;
+        if (typeof body === 'string') return body;
+
+        // URLSearchParams — safe to stringify synchronously
+        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+            return body.toString();
+        }
+
+        // FormData — reading is async and would consume the stream
+        if (typeof FormData !== 'undefined' && body instanceof FormData) {
+            return { kind: 'unreadable', reason: 'FormData' };
+        }
+
+        // ReadableStream — cannot read without consuming. Referenced via globalThis
+        // because it isn't in the RN/Hermes lib types and is undefined on some
+        // Hermes builds.
+        const ReadableStreamCtor = (globalThis as any).ReadableStream;
+        if (ReadableStreamCtor && body instanceof ReadableStreamCtor) {
+            return { kind: 'unreadable', reason: 'ReadableStream' };
+        }
+
+        // Blob — async read, skip here
+        if (typeof Blob !== 'undefined' && body instanceof Blob) {
+            return { kind: 'unreadable', reason: 'Blob' };
+        }
+
+        // ArrayBuffer / TypedArray — binary, no meaningful text representation
+        if (body instanceof ArrayBuffer) {
+            return { kind: 'unreadable', reason: 'ArrayBuffer' };
+        }
+
+        // Unknown type — record but don't crash
+        return { kind: 'unreadable', reason: 'unknown' };
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── Fetch Response Body Extraction ─────────────────────────────────────────
+
+/**
+ * Read the fetch response body asynchronously using `response.clone()` so
+ * the original response stream remains intact for the caller.
+ *
+ * Skips binary content-types. Truncates at `maxBytes`.
+ * Never throws — returns a SkippedBody or UnreadableBody on any failure.
+ */
+export async function extractResponseBodyFromFetch(
+    response: Response,
+    maxBytes: number,
+): Promise<CapturedBody> {
+    try {
+        const contentType = response.headers.get('content-type');
+
+        // Skip non-textual content
+        if (isBinaryContentType(contentType)) {
+            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
+        }
+
+        // Clone before reading — preserves the original stream for the caller
+        const clone = response.clone();
+        const text = await clone.text();
+
+        return truncateBody(text, maxBytes);
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── XHR Response Body Extraction ────────────────────────────────────────────
+
+/**
+ * Extract the XHR response body from `xhr.responseText`.
+ *
+ * Skips binary content-types. Truncates at `maxBytes`.
+ * Never throws.
+ */
+export function extractResponseBodyFromXHR(
+    responseText: string | null | undefined,
+    contentType: string | null | undefined,
+    maxBytes: number,
+): CapturedBody {
+    try {
+        if (isBinaryContentType(contentType)) {
+            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
+        }
+        if (responseText === null || responseText === undefined) return null;
+        return truncateBody(responseText, maxBytes);
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── Body Truncation ─────────────────────────────────────────────────────────
+
+/**
+ * Truncate a text body to `maxBytes` (counted in UTF-16 code units, which
+ * is the natural unit for JS strings and keeps the implementation simple and
+ * fast without a TextEncoder round-trip).
+ *
+ * If the body fits, it is returned as-is (possibly JSON-parsed for object inspection).
+ * If it exceeds the cap, returns a TruncatedBody marker.
+ */
+function truncateBody(text: string, maxBytes: number): CapturedBody {
+    if (text.length <= maxBytes) {
+        // Attempt JSON parse for structured display in the desktop panel
+        try {
+            return JSON.parse(text);
+        } catch {
+            return text;
+        }
+    }
+
+    const preview = text.slice(0, maxBytes);
+    return {
+        kind: 'truncated',
+        preview,
+        totalBytes: text.length,
+        capturedBytes: maxBytes,
+    };
+}
+
+// ─── Header Extraction ────────────────────────────────────────────────────────
+
+/**
+ * Normalise a fetch `Headers` object, `HeadersInit` value, or a plain
+ * `Record<string, string>` into a flat `Record<string, string>`.
+ *
+ * Returns an empty object on any failure.
+ * Never throws.
+ */
+export function extractFetchRequestHeaders(
+    headers: HeadersInit_ | undefined,
+): Record<string, string> {
+    if (!headers) return {};
+    try {
+        if (headers instanceof Headers) {
+            return headersToRecord(headers);
+        }
+        if (Array.isArray(headers)) {
+            return Object.fromEntries(headers);
+        }
+        // Plain object
+        return { ...(headers as Record<string, string>) };
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Convert a fetch `Headers` object to a plain `Record<string, string>`.
+ * Never throws.
+ */
+export function headersToRecord(headers: Headers): Record<string, string> {
+    const result: Record<string, string> = {};
+    try {
+        headers.forEach((value: string, key: string) => {
+            result[key] = value;
+        });
+    } catch {
+        // Partial result is acceptable
+    }
+    return result;
+}
+
+/**
+ * Parse XHR `getAllResponseHeaders()` string into a `Record<string, string>`.
+ * The raw string format is `"key: value\r\nkey2: value2\r\n"`.
+ * Never throws.
+ */
+export function parseXHRResponseHeaders(raw: string | null): Record<string, string> {
+    if (!raw) return {};
+    const result: Record<string, string> = {};
+    try {
+        for (const line of raw.split('\r\n')) {
+            const colonIndex = line.indexOf(': ');
+            if (colonIndex === -1) continue;
+            const key = line.slice(0, colonIndex).trim().toLowerCase();
+            const value = line.slice(colonIndex + 2).trim();
+            if (key) result[key] = value;
+        }
+    } catch {
+        // Partial result is acceptable
+    }
+    return result;
+}

package/src/integrations/xhr/xhrInterceptor.ts

@@ -0,0 +1,259 @@
+/**
+ * ScaleBun SDK — XHR Interceptor
+ *
+ * Monkey-patches `XMLHttpRequest` to capture network events.
+ *
+ * When `captureNetworkBodies` is enabled:
+ *   - Request headers: shimmed via `setRequestHeader` to record headers
+ *     before `send()` is called.
+ *   - Response headers: parsed from `getAllResponseHeaders()` in the `load`
+ *     handler.
+ *   - Request body: captured from the `send(body)` argument (strings only;
+ *     FormData / ArrayBuffer etc. get a placeholder).
+ *   - Response body: read from `xhr.responseText` after the response
+ *     arrives, truncated to `networkBodyMaxBytes`. Binary content-types
+ *     are skipped.
+ *   - All headers and bodies pass through `redactNetworkEvent` when
+ *     `redactNetwork` is true.
+ *
+ * ⚠️  PRIVACY: Body capture is opt-in via `captureNetworkBodies: true`.
+ * The integrator is responsible for compliance with applicable privacy
+ * regulations (GDPR, CCPA, etc.) and their own privacy policy.
+ *
+ * Scope: JS-host (XHR) only.
+ * Native-layer capture (OkHttp / URLSession) is a separate future task.
+ */
+
+import { noThrow } from '../../core/lifecycle/crashSafe';
+import { logger } from '../../core/logger/internalLogger';
+import {
+    extractRequestBody,
+    extractResponseBodyFromXHR,
+    parseXHRResponseHeaders,
+    requestBodyBytes,
+    contentLengthBytes,
+    DEFAULT_BODY_MAX_BYTES,
+} from '../network/bodyCapture';
+import { redactNetworkEvent } from '../../debug/redaction';
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface XHRInterceptorOptions {
+    /** Capture request/response headers and bodies. Default: false */
+    captureNetworkBodies?: boolean;
+    /** Max bytes to capture per body before truncating. Default: 65536 */
+    networkBodyMaxBytes?: number;
+    /** Apply redaction pipeline to captured headers/bodies. Default: true (fail closed) */
+    redactNetwork?: boolean;
+    /**
+     * Lifecycle ping for consumers that need to know a request is IN FLIGHT, not just what it
+     * turned out to be. `onEvent` fires once, on completion, and carries the whole record — which
+     * is the right shape for telemetry and useless for "is this screen still waiting".
+     *
+     * `end` is raised from `loadend`, which the platform dispatches exactly once for every
+     * terminal state — load, error, abort and timeout alike. The `load` and `error` handlers
+     * below deliberately do NOT carry it: they cover only two of the four, so pairing on them
+     * would leak a start for every cancelled request.
+     */
+    onRequestPhase?: (phase: 'start' | 'end', url: string) => void;
+}
+
+// ─── Interceptor ─────────────────────────────────────────────────────────────
+
+export function installXHRInterceptor(
+    onEvent: (data: any) => void,
+    options: XHRInterceptorOptions = {},
+): void {
+    noThrow(() => {
+        const XMLHttpRequest = (globalThis as any).XMLHttpRequest;
+        if (!XMLHttpRequest) {
+            logger.warn('XMLHttpRequest not found, skipping interceptor');
+            return;
+        }
+
+        const captureBodies = options.captureNetworkBodies ?? false;
+        const maxBytes = options.networkBodyMaxBytes ?? DEFAULT_BODY_MAX_BYTES;
+        // Privacy fails CLOSED: redaction is on unless explicitly opted out.
+        const shouldRedact = options.redactNetwork ?? true;
+
+        const originalOpen = XMLHttpRequest.prototype.open;
+        const originalSend = XMLHttpRequest.prototype.send;
+        const originalSetRequestHeader = XMLHttpRequest.prototype.setRequestHeader;
+
+        // ── open(): record method + URL + reset captured headers ───────────
+        XMLHttpRequest.prototype.open = function (method: string, url: string) {
+            this._scalebun_method = method.toUpperCase();
+            this._scalebun_url = url;
+            this._scalebun_start = Date.now();
+            // Reset per-request state
+            this._scalebun_requestHeaders = {};
+            return originalOpen.apply(this, arguments as any);
+        };
+
+        // ── setRequestHeader(): accumulate request headers (if capturing) ──
+        XMLHttpRequest.prototype.setRequestHeader = function (name: string, value: string) {
+            if (captureBodies && this._scalebun_requestHeaders !== undefined) {
+                // Lowercase keys for consistency with fetch header convention
+                this._scalebun_requestHeaders[name.toLowerCase()] = value;
+            }
+            return originalSetRequestHeader.apply(this, arguments as any);
+        };
+
+        // ── send(): capture request body + wire load/error handlers ────────
+        XMLHttpRequest.prototype.send = function (body?: any) {
+            // Byte count is non-PII → always measured (independent of body capture).
+            this._scalebun_requestSize = requestBodyBytes(body);
+
+            // ── In-flight ping ─────────────────────────────────────────────
+            // Paired on loadend so abort/timeout close the request too. Guarded against a
+            // double send() on one instance, which would otherwise report two starts and one end.
+            if (options.onRequestPhase && !this._scalebun_phaseOpen) {
+                const phaseUrl = String(this._scalebun_url ?? '');
+                this._scalebun_phaseOpen = true;
+                noThrow(() => options.onRequestPhase?.('start', phaseUrl));
+                this.addEventListener('loadend', () => {
+                    if (!this._scalebun_phaseOpen) return;
+                    this._scalebun_phaseOpen = false;
+                    // The SAME url the start was reported with, captured at send() rather than
+                    // re-read here: a redirect rewrites `responseURL`, and an end filtered by a
+                    // different url than its start is an unbalanced pair.
+                    noThrow(() => options.onRequestPhase?.('end', phaseUrl));
+                });
+            }
+
+            // Capture request body synchronously before send
+            let requestBody: unknown | undefined;
+            if (captureBodies) {
+                requestBody = extractRequestBody(body);
+                this._scalebun_requestBody = requestBody;
+            }
+
+            // ── Load handler ───────────────────────────────────────────────
+            this.addEventListener('load', () => {
+                noThrow(() => {
+                    const duration = Date.now() - this._scalebun_start;
+
+                    let responseHeaders: Record<string, string> | undefined;
+                    let responseBody: unknown | undefined;
+                    let capturedRequestHeaders: Record<string, string> | undefined;
+                    let capturedRequestBody: unknown | undefined;
+
+                    if (captureBodies) {
+                        capturedRequestHeaders = this._scalebun_requestHeaders ?? {};
+                        capturedRequestBody = this._scalebun_requestBody;
+
+                        // Parse response headers
+                        const rawHeaders = this.getAllResponseHeaders();
+                        responseHeaders = parseXHRResponseHeaders(rawHeaders);
+
+                        // Extract response body. responseText is ONLY readable when
+                        // responseType is '' or 'text'; for 'blob'/'arraybuffer'/'json'
+                        // accessing it throws ("responseText is only available if
+                        // responseType is '' or 'text'"). Guard so we skip the body
+                        // instead of raising a non-fatal error per request.
+                        const contentType = this.getResponseHeader('content-type');
+                        const rt = this.responseType;
+                        const safeText =
+                            rt === '' || rt === 'text' ? this.responseText : null;
+                        responseBody = extractResponseBodyFromXHR(
+                            safeText,
+                            contentType,
+                            maxBytes,
+                        );
+                    }
+
+                    // Apply redaction pipeline
+                    let finalRequestHeaders = capturedRequestHeaders;
+                    let finalResponseHeaders = responseHeaders;
+                    let finalRequestBody = capturedRequestBody;
+                    let finalResponseBody = responseBody;
+                    let piiWarnings: any[] | undefined;
+
+                    if (captureBodies && shouldRedact) {
+                        const redacted = redactNetworkEvent({
+                            url: this._scalebun_url,
+                            method: this._scalebun_method,
+                            status: this.status,
+                            duration,
+                            requestHeaders: capturedRequestHeaders,
+                            responseHeaders,
+                            requestBody: capturedRequestBody,
+                            responseBody,
+                        });
+                        finalRequestHeaders = redacted.requestHeaders;
+                        finalResponseHeaders = redacted.responseHeaders;
+                        finalRequestBody = redacted.requestBody;
+                        finalResponseBody = redacted.responseBody;
+                        piiWarnings = redacted.piiWarnings;
+                    }
+
+                    onEvent({
+                        type: 'network',
+                        method: this._scalebun_method,
+                        url: this._scalebun_url,
+                        status: this.status,
+                        statusText: this.statusText,
+                        duration,
+                        requestSize: this._scalebun_requestSize ?? 0,
+                        responseSize: contentLengthBytes(this.getResponseHeader('content-length')),
+                        ...(captureBodies && {
+                            requestHeaders: finalRequestHeaders,
+                            responseHeaders: finalResponseHeaders,
+                            requestBody: finalRequestBody,
+                            responseBody: finalResponseBody,
+                            ...(piiWarnings !== undefined && { piiWarnings }),
+                        }),
+                    });
+                });
+            });
+
+            // ── Error handler ──────────────────────────────────────────────
+            this.addEventListener('error', () => {
+                noThrow(() => {
+                    const duration = Date.now() - this._scalebun_start;
+
+                    // Redact identically to the load/success path — the error
+                    // branch MUST NOT leak Authorization/Cookie headers or body.
+                    let finalRequestHeaders = this._scalebun_requestHeaders;
+                    let finalRequestBody = this._scalebun_requestBody;
+                    let piiWarnings: any[] | undefined;
+
+                    if (captureBodies && shouldRedact) {
+                        const redacted = redactNetworkEvent({
+                            url: this._scalebun_url,
+                            method: this._scalebun_method,
+                            status: 0,
+                            duration,
+                            requestHeaders: this._scalebun_requestHeaders,
+                            requestBody: this._scalebun_requestBody,
+                        });
+                        finalRequestHeaders = redacted.requestHeaders;
+                        finalRequestBody = redacted.requestBody;
+                        piiWarnings = redacted.piiWarnings;
+                    }
+
+                    onEvent({
+                        type: 'network',
+                        method: this._scalebun_method,
+                        url: this._scalebun_url,
+                        status: 0,
+                        error: 'XMLHttpRequest error',
+                        duration,
+                        requestSize: this._scalebun_requestSize ?? 0,
+                        ...(captureBodies && finalRequestHeaders !== undefined && {
+                            requestHeaders: finalRequestHeaders,
+                        }),
+                        ...(captureBodies && finalRequestBody !== undefined && {
+                            requestBody: finalRequestBody,
+                        }),
+                        ...(piiWarnings !== undefined && { piiWarnings }),
+                    });
+                });
+            });
+
+            return originalSend.apply(this, arguments as any);
+        };
+
+        __DEV__ && logger.debug('XHR Interceptor installed');
+    });
+}