@scalebun-release/react-native 2.5.0

package/lib/module/integrations/network/bodyCapture.js

@@ -0,0 +1,320 @@
+/**
+ * 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). */
+
+/** Marker emitted when a body is truncated to fit the byte cap. */
+
+/** Marker emitted when the content-type indicates binary/non-textual content. */
+
+// ─── 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) {
+  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) {
+  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) {
+  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)) return body.byteLength;
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Parse a `content-length` header value to a byte count. 0 when absent/invalid. */
+export function contentLengthBytes(value) {
+  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) {
+  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.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, maxBytes) {
+  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, contentType, maxBytes) {
+  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, maxBytes) {
+  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) {
+  if (!headers) return {};
+  try {
+    if (headers instanceof Headers) {
+      return headersToRecord(headers);
+    }
+    if (Array.isArray(headers)) {
+      return Object.fromEntries(headers);
+    }
+    // Plain object
+    return {
+      ...headers
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Convert a fetch `Headers` object to a plain `Record<string, string>`.
+ * Never throws.
+ */
+export function headersToRecord(headers) {
+  const result = {};
+  try {
+    headers.forEach((value, key) => {
+      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) {
+  if (!raw) return {};
+  const result = {};
+  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;
+}
+//# sourceMappingURL=bodyCapture.js.map

package/lib/module/integrations/xhr/xhrInterceptor.js

@@ -0,0 +1,219 @@
+/**
+ * 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 ───────────────────────────────────────────────────────────────────
+
+// ─── Interceptor ─────────────────────────────────────────────────────────────
+
+export function installXHRInterceptor(onEvent, options = {}) {
+  noThrow(() => {
+    const XMLHttpRequest = globalThis.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, url) {
+      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);
+    };
+
+    // ── setRequestHeader(): accumulate request headers (if capturing) ──
+    XMLHttpRequest.prototype.setRequestHeader = function (name, value) {
+      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);
+    };
+
+    // ── send(): capture request body + wire load/error handlers ────────
+    XMLHttpRequest.prototype.send = function (body) {
+      // 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;
+      if (captureBodies) {
+        requestBody = extractRequestBody(body);
+        this._scalebun_requestBody = requestBody;
+      }
+
+      // ── Load handler ───────────────────────────────────────────────
+      this.addEventListener('load', () => {
+        noThrow(() => {
+          const duration = Date.now() - this._scalebun_start;
+          let responseHeaders;
+          let responseBody;
+          let capturedRequestHeaders;
+          let capturedRequestBody;
+          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;
+          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;
+          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);
+    };
+    __DEV__ && logger.debug('XHR Interceptor installed');
+  });
+}
+//# sourceMappingURL=xhrInterceptor.js.map

package/lib/module/metro/composeSourceMap.js

@@ -0,0 +1,97 @@
+/**
+ * ScaleBun SDK — source-map composition for the pre-bundled artifact.
+ *
+ * The SDK ships as one scope-hoisted file (dist/scalebun.*.js). Metro's map therefore resolves
+ * every SDK frame to that single generated file, and Metro cannot chain the artifact's own map
+ * (no inputSourceMap support anywhere in metro-transform-worker). Left like that, a production
+ * crash inside the SDK symbolicates to one opaque file:line — for a crash-reporting SDK that is
+ * self-sabotage.
+ *
+ * This module performs the missing chain step: every mapping in the app's final map that lands in
+ * a ScaleBun artifact is re-resolved through the artifact's stage-2 map (which itself chains via
+ * bob's per-file maps back to the original TypeScript). It runs inside `withScaleBun`'s
+ * serializer wrapper, so the .map Metro writes to disk is already correct — for ScaleBun's own
+ * backend and for any third-party tool the host uploads maps to, with zero consumer action.
+ *
+ * Node-only (metro.config.js context). Never part of the app bundle.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+import { decode, encode } from '@jridgewell/sourcemap-codec';
+const normalize = p => p.replace(/\\/g, '/');
+
+/**
+ * Rewrite `metroMap` so mappings pointing into any of `artifacts` resolve through that artifact's
+ * stage-2 map. Returns the number of rewritten segments (0 = nothing matched, map returned as-is).
+ *
+ * The input object is mutated and returned — serialization happens exactly once, in the caller.
+ */
+export function composeSourceMap(metroMap, artifacts) {
+  // Index of each artifact in the outer map's source list, if present at all.
+  const byIndex = new Map();
+  for (const {
+    artifactPath,
+    mapPath
+  } of artifacts) {
+    const wanted = normalize(artifactPath);
+    const idx = metroMap.sources.findIndex(s => s != null && normalize(s) === wanted);
+    if (idx < 0) continue;
+    const trace = new TraceMap(JSON.parse(fs.readFileSync(mapPath, 'utf8')));
+    byIndex.set(idx, {
+      trace,
+      mapDir: path.dirname(mapPath)
+    });
+  }
+  if (byIndex.size === 0) return {
+    map: metroMap,
+    rewritten: 0
+  };
+  const sourcesContent = metroMap.sourcesContent ??= [];
+  while (sourcesContent.length < metroMap.sources.length) sourcesContent.push(null);
+
+  /** stage-2 source (resolved against its map's directory) → index in the outer source list. */
+  const appended = new Map();
+  const indexFor = (mapDir, source, content) => {
+    // build-dist rewrites stage-2 sources to package-relative "src/…", and the maps live in
+    // <packageRoot>/dist — so resolve against the map directory's PARENT to yield
+    // "<packageRoot>/src/…" like every other absolute path in the outer map.
+    const abs = normalize(path.resolve(path.dirname(mapDir), source));
+    const hit = appended.get(abs);
+    if (hit !== undefined) return hit;
+    metroMap.sources.push(abs);
+    sourcesContent.push(content);
+    const idx = metroMap.sources.length - 1;
+    appended.set(abs, idx);
+    return idx;
+  };
+  const decoded = decode(metroMap.mappings);
+  let rewritten = 0;
+  for (const line of decoded) {
+    for (const seg of line) {
+      if (seg.length < 4) continue;
+      const hit = byIndex.get(seg[1]);
+      if (!hit) continue;
+      const pos = originalPositionFor(hit.trace, {
+        line: seg[2] + 1,
+        column: seg[3]
+      });
+      if (pos.source == null || pos.line == null) continue;
+      const srcIdx = hit.trace.resolvedSources.indexOf(pos.source);
+      const content = srcIdx >= 0 ? hit.trace.sourcesContent?.[srcIdx] ?? null : null;
+      seg[1] = indexFor(hit.mapDir, pos.source, content);
+      seg[2] = pos.line - 1;
+      seg[3] = pos.column;
+      // Drop the name index: it refers to the outer map's name table, which is meaningless
+      // for a position that now lives in the stage-2 map's coordinate space.
+      if (seg.length === 5) seg.length = 4;
+      rewritten++;
+    }
+  }
+  metroMap.mappings = encode(decoded);
+  return {
+    map: metroMap,
+    rewritten
+  };
+}
+//# sourceMappingURL=composeSourceMap.js.map