browsertrack 0.0.1 → 0.1.0

package/packages/core/dist/index.js

@@ -0,0 +1,221 @@
+// src/fingerprint.ts
+function normalizeErrorMessage(message) {
+  if (!message) return "unknown_error";
+  return message.trim().replace(/0x[0-9a-fA-F]+/g, "0x<HEX>").replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, "<UUID>").replace(/\?[tv]=[\w.-]+/g, "").replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?/g, "<TIMESTAMP>").replace(/#\d+/g, "#<ID>").replace(/\s+/g, " ");
+}
+function normalizeSourceFile(filename) {
+  if (!filename) return "unknown_source";
+  let cleaned = filename.trim();
+  try {
+    if (cleaned.startsWith("http://") || cleaned.startsWith("https://")) {
+      const url = new URL(cleaned);
+      cleaned = url.pathname;
+    }
+  } catch {
+    cleaned = cleaned.replace(/^https?:\/\/[^/]+/, "");
+  }
+  cleaned = cleaned.split("?")[0].split("#")[0];
+  cleaned = cleaned.replace(/\\/g, "/");
+  return cleaned || "unknown_source";
+}
+function extractSourceFromStack(stack) {
+  if (!stack) return null;
+  const lines = stack.split("\n");
+  for (const line of lines) {
+    const match = line.match(/(?:at\s+(?:.*?\s+\()?)?(https?:\/\/[^\s)]+|file:\/\/[^\s)]+|\/[^\s)]+):(\d+):(\d+)\)?/);
+    if (match) {
+      return {
+        file: normalizeSourceFile(match[1]),
+        line: parseInt(match[2], 10),
+        column: parseInt(match[3], 10)
+      };
+    }
+  }
+  return null;
+}
+function djb2Hash(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = hash * 33 ^ str.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function computeFingerprint(input) {
+  const normType = (input.type || "Error").trim().toLowerCase();
+  const normMsg = normalizeErrorMessage(input.message);
+  let sourceFile = normalizeSourceFile(input.sourceFile);
+  let line = input.line || 0;
+  if ((sourceFile === "unknown_source" || line === 0) && input.stack) {
+    const extracted = extractSourceFromStack(input.stack);
+    if (extracted) {
+      sourceFile = extracted.file;
+      line = extracted.line;
+    }
+  }
+  const rawKey = `${normType}::${normMsg}::${sourceFile}::${line}`;
+  const hash = djb2Hash(rawKey);
+  return `fp_${hash}`;
+}
+
+// src/redaction.ts
+var SENSITIVE_KEY_PATTERNS = [
+  /^authorization$/i,
+  /^cookie$/i,
+  /^set-cookie$/i,
+  /password/i,
+  /token/i,
+  /secret/i,
+  /apikey/i,
+  /api_key/i,
+  /access_token/i,
+  /refresh_token/i,
+  /auth/i,
+  /credentials/i,
+  /private_key/i,
+  /ssn/i,
+  /credit_card/i,
+  /cvv/i
+];
+var SENSITIVE_QUERY_PARAMS = [
+  "token",
+  "auth",
+  "key",
+  "apikey",
+  "api_key",
+  "secret",
+  "password",
+  "access_token",
+  "refresh_token",
+  "code",
+  "signature"
+];
+var REDACTED_PLACEHOLDER = "[REDACTED]";
+function isSensitiveKey(key) {
+  if (!key) return false;
+  return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+function redactUrl(rawUrl) {
+  if (!rawUrl) return rawUrl;
+  try {
+    const isRelative = !rawUrl.startsWith("http://") && !rawUrl.startsWith("https://") && !rawUrl.startsWith("ws://") && !rawUrl.startsWith("wss://");
+    const base = "http://localhost";
+    const parsed = new URL(rawUrl, base);
+    let changed = false;
+    for (const param of SENSITIVE_QUERY_PARAMS) {
+      if (parsed.searchParams.has(param)) {
+        parsed.searchParams.set(param, REDACTED_PLACEHOLDER);
+        changed = true;
+      }
+    }
+    for (const key of Array.from(parsed.searchParams.keys())) {
+      if (isSensitiveKey(key)) {
+        parsed.searchParams.set(key, REDACTED_PLACEHOLDER);
+        changed = true;
+      }
+    }
+    if (!changed) return rawUrl;
+    if (isRelative) {
+      return parsed.pathname + parsed.search + parsed.hash;
+    }
+    return parsed.toString();
+  } catch {
+    let safe = rawUrl;
+    for (const param of SENSITIVE_QUERY_PARAMS) {
+      const reg = new RegExp(`([?&]${param}=)[^&#]+`, "gi");
+      safe = safe.replace(reg, `$1${REDACTED_PLACEHOLDER}`);
+    }
+    return safe;
+  }
+}
+function redactHeaders(headers) {
+  if (!headers || typeof headers !== "object") return {};
+  const safe = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (isSensitiveKey(key)) {
+      safe[key] = REDACTED_PLACEHOLDER;
+    } else {
+      safe[key] = value;
+    }
+  }
+  return safe;
+}
+function redactSensitiveData(data, maxDepth = 4, currentDepth = 0) {
+  if (data === null || data === void 0) return data;
+  if (typeof data !== "object") return data;
+  if (currentDepth > maxDepth) return "[DEPTH_EXCEEDED]";
+  if (Array.isArray(data)) {
+    return data.map((item) => redactSensitiveData(item, maxDepth, currentDepth + 1));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (isSensitiveKey(key)) {
+      result[key] = REDACTED_PLACEHOLDER;
+    } else if (typeof value === "string") {
+      if (value.startsWith("http://") || value.startsWith("https://") || value.includes("?")) {
+        result[key] = redactUrl(value);
+      } else {
+        result[key] = value;
+      }
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = redactSensitiveData(value, maxDepth, currentDepth + 1);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// src/selector.ts
+function getSemanticSelector(element, options = {}) {
+  if (!element || !element.tagName) return "unknown";
+  const maxClasses = options.maxClasses ?? 2;
+  const testId = element.getAttribute("data-testid") || element.getAttribute("data-test") || element.getAttribute("data-cy") || element.getAttribute("data-qa");
+  if (testId) {
+    return `[data-testid="${testId}"]`;
+  }
+  const id = element.id;
+  if (id && !/^[0-9]+$/.test(id) && !/[0-9a-f]{8}-[0-9a-f]{4}/i.test(id)) {
+    return `#${id}`;
+  }
+  const ariaLabel = element.getAttribute("aria-label");
+  if (ariaLabel && ariaLabel.length < 30) {
+    return `${element.tagName.toLowerCase()}[aria-label="${ariaLabel}"]`;
+  }
+  const nameAttr = element.getAttribute("name");
+  if (nameAttr) {
+    return `${element.tagName.toLowerCase()}[name="${nameAttr}"]`;
+  }
+  const tag = element.tagName.toLowerCase();
+  const classList = Array.from(element.classList || []).filter((c) => !c.startsWith("css-") && !c.startsWith("_") && !/^[a-z0-9]{5,}$/i.test(c)).slice(0, maxClasses);
+  if (classList.length > 0) {
+    const classStr = classList.map((c) => `.${c}`).join("");
+    return `${tag}${classStr}`;
+  }
+  if (element.parentElement && element.parentElement !== document.body && element.parentElement !== document.documentElement) {
+    const parentSelector = getSemanticSelector(element.parentElement, { maxClasses: 1 });
+    if (parentSelector && parentSelector !== "unknown" && !parentSelector.includes(">")) {
+      return `${parentSelector} > ${tag}`;
+    }
+  }
+  return tag;
+}
+function truncate(str, maxLength = 200) {
+  if (!str) return "";
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + "...";
+}
+export {
+  REDACTED_PLACEHOLDER,
+  SENSITIVE_KEY_PATTERNS,
+  SENSITIVE_QUERY_PARAMS,
+  computeFingerprint,
+  extractSourceFromStack,
+  getSemanticSelector,
+  isSensitiveKey,
+  normalizeErrorMessage,
+  normalizeSourceFile,
+  redactHeaders,
+  redactSensitiveData,
+  redactUrl,
+  truncate
+};

package/packages/core/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@browserdiag/core",
+  "version": "0.1.0",
+  "description": "Core types, schemas, fingerprinting, and utilities for browserdiag",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}

package/packages/core/src/fingerprint.ts

@@ -0,0 +1,120 @@
+/**
+ * Error fingerprinting and normalization utilities
+ */
+
+export interface FingerprintInput {
+  type: string;
+  message: string;
+  sourceFile?: string;
+  line?: number;
+  column?: number;
+  stack?: string;
+}
+
+/**
+ * Normalizes error messages by stripping dynamic content like UUIDs, timestamps,
+ * hex addresses, and file timestamps.
+ */
+export function normalizeErrorMessage(message: string): string {
+  if (!message) return 'unknown_error';
+
+  return message
+    // Normalize string representation
+    .trim()
+    // Replace hex addresses (e.g. 0x7ffee4b2a8)
+    .replace(/0x[0-9a-fA-F]+/g, '0x<HEX>')
+    // Replace UUIDs
+    .replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '<UUID>')
+    // Replace timestamp query params like ?t=1719283748 or ?v=1.2.3
+    .replace(/\?[tv]=[\w.-]+/g, '')
+    // Replace ISO timestamps
+    .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?/g, '<TIMESTAMP>')
+    // Replace numbers in quotes/brackets if likely IDs (e.g., user "12345")
+    .replace(/#\d+/g, '#<ID>')
+    // Normalize whitespaces
+    .replace(/\s+/g, ' ');
+}
+
+/**
+ * Normalizes source filenames by removing origin and cache-busting query strings.
+ */
+export function normalizeSourceFile(filename?: string): string {
+  if (!filename) return 'unknown_source';
+
+  let cleaned = filename.trim();
+  // Strip protocol and origin if present (e.g. http://localhost:5173/src/App.tsx?t=123)
+  try {
+    if (cleaned.startsWith('http://') || cleaned.startsWith('https://')) {
+      const url = new URL(cleaned);
+      cleaned = url.pathname;
+    }
+  } catch {
+    // fallback string manipulation
+    cleaned = cleaned.replace(/^https?:\/\/[^/]+/, '');
+  }
+
+  // Remove query parameters
+  cleaned = cleaned.split('?')[0].split('#')[0];
+
+  // Normalize windows path separators
+  cleaned = cleaned.replace(/\\/g, '/');
+
+  return cleaned || 'unknown_source';
+}
+
+/**
+ * Extracts source location from stack if not explicitly provided
+ */
+export function extractSourceFromStack(stack?: string): { file: string; line: number; column?: number } | null {
+  if (!stack) return null;
+
+  const lines = stack.split('\n');
+  for (const line of lines) {
+    // Match standard stack line: at functionName (http://localhost:5173/src/main.tsx:15:3) or at http://...:15:3
+    const match = line.match(/(?:at\s+(?:.*?\s+\()?)?(https?:\/\/[^\s)]+|file:\/\/[^\s)]+|\/[^\s)]+):(\d+):(\d+)\)?/);
+    if (match) {
+      return {
+        file: normalizeSourceFile(match[1]),
+        line: parseInt(match[2], 10),
+        column: parseInt(match[3], 10),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Fast synchronous djb2-based hash for universal client/server runtime
+ */
+function djb2Hash(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i);
+  }
+  // Convert to unsigned 32-bit hex string
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/**
+ * Computes a deterministic fingerprint for an error
+ */
+export function computeFingerprint(input: FingerprintInput): string {
+  const normType = (input.type || 'Error').trim().toLowerCase();
+  const normMsg = normalizeErrorMessage(input.message);
+
+  let sourceFile = normalizeSourceFile(input.sourceFile);
+  let line = input.line || 0;
+
+  if ((sourceFile === 'unknown_source' || line === 0) && input.stack) {
+    const extracted = extractSourceFromStack(input.stack);
+    if (extracted) {
+      sourceFile = extracted.file;
+      line = extracted.line;
+    }
+  }
+
+  const rawKey = `${normType}::${normMsg}::${sourceFile}::${line}`;
+  const hash = djb2Hash(rawKey);
+
+  return `fp_${hash}`;
+}

package/packages/core/src/index.ts

@@ -0,0 +1,9 @@
+export * from './types/events.js';
+export * from './types/incidents.js';
+export * from './types/commands.js';
+export * from './types/probes.js';
+export * from './types/projects.js';
+export * from './types/notes.js';
+export * from './fingerprint.js';
+export * from './redaction.js';
+export * from './selector.js';

package/packages/core/src/redaction.ts

@@ -0,0 +1,139 @@
+/**
+ * Security and Redaction Utilities
+ */
+
+export const SENSITIVE_KEY_PATTERNS = [
+  /^authorization$/i,
+  /^cookie$/i,
+  /^set-cookie$/i,
+  /password/i,
+  /token/i,
+  /secret/i,
+  /api[-_]?key/i,
+  /access[-_]?token/i,
+  /refresh[-_]?token/i,
+  /credentials/i,
+  /private[-_]?key/i,
+  /ssn/i,
+  /credit[-_]?card/i,
+  /cvv/i,
+];
+
+export const SENSITIVE_QUERY_PARAMS = [
+  'token',
+  'auth',
+  'key',
+  'apikey',
+  'api_key',
+  'secret',
+  'password',
+  'access_token',
+  'refresh_token',
+  'code',
+  'signature',
+];
+
+export const REDACTED_PLACEHOLDER = '[REDACTED]';
+
+/**
+ * Checks if a property name matches any sensitive pattern
+ */
+export function isSensitiveKey(key: string): boolean {
+  if (!key) return false;
+  const cleaned = key.replace(/[-_]/g, '');
+  return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key) || pattern.test(cleaned));
+}
+
+/**
+ * Redacts sensitive query parameters from a URL string
+ */
+export function redactUrl(rawUrl: string): string {
+  if (!rawUrl) return rawUrl;
+
+  try {
+    const isRelative = !rawUrl.startsWith('http://') && !rawUrl.startsWith('https://') && !rawUrl.startsWith('ws://') && !rawUrl.startsWith('wss://');
+    const base = 'http://localhost';
+    const parsed = new URL(rawUrl, base);
+
+    let changed = false;
+    for (const param of SENSITIVE_QUERY_PARAMS) {
+      if (parsed.searchParams.has(param)) {
+        parsed.searchParams.set(param, REDACTED_PLACEHOLDER);
+        changed = true;
+      }
+    }
+
+    // Also check all query params against isSensitiveKey
+    for (const key of Array.from(parsed.searchParams.keys())) {
+      if (isSensitiveKey(key)) {
+        parsed.searchParams.set(key, REDACTED_PLACEHOLDER);
+        changed = true;
+      }
+    }
+
+    if (!changed) return rawUrl;
+
+    let result = isRelative ? parsed.pathname + parsed.search + parsed.hash : parsed.toString();
+    // Normalize URL-encoded brackets %5BREDACTED%5D back to [REDACTED]
+    result = result.replace(/%5BREDACTED%5D/g, REDACTED_PLACEHOLDER);
+    return result;
+  } catch {
+    // If URL parsing fails, perform regex replace
+    let safe = rawUrl;
+    for (const param of SENSITIVE_QUERY_PARAMS) {
+      const reg = new RegExp(`([?&]${param}=)[^&#]+`, 'gi');
+      safe = safe.replace(reg, `$1${REDACTED_PLACEHOLDER}`);
+    }
+    return safe;
+  }
+}
+
+/**
+ * Redacts sensitive HTTP headers
+ */
+export function redactHeaders(headers: Record<string, string>): Record<string, string> {
+  if (!headers || typeof headers !== 'object') return {};
+
+  const safe: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (isSensitiveKey(key)) {
+      safe[key] = REDACTED_PLACEHOLDER;
+    } else {
+      safe[key] = value;
+    }
+  }
+  return safe;
+}
+
+/**
+ * Deeply redacts sensitive keys from an object or array
+ */
+export function redactSensitiveData<T = any>(data: T, maxDepth = 6, currentDepth = 0): T {
+  if (data === null || data === undefined) return data;
+  if (typeof data !== 'object') return data;
+  if (currentDepth > maxDepth) return '[DEPTH_EXCEEDED]' as any;
+
+  if (Array.isArray(data)) {
+    return data.map((item) => redactSensitiveData(item, maxDepth, currentDepth + 1)) as any;
+  }
+
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(data as Record<string, any>)) {
+    if (typeof value === 'object' && value !== null) {
+      result[key] = redactSensitiveData(value, maxDepth, currentDepth + 1);
+    } else if (isSensitiveKey(key)) {
+      result[key] = REDACTED_PLACEHOLDER;
+    } else if (typeof value === 'string') {
+      // Check if value is a URL containing secrets
+      if (value.startsWith('http://') || value.startsWith('https://') || value.includes('?')) {
+        result[key] = redactUrl(value);
+      } else {
+        result[key] = value;
+      }
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result as T;
+}

package/packages/core/src/selector.ts

@@ -0,0 +1,77 @@
+/**
+ * Semantic element selector generation and inspection
+ */
+
+export interface SelectorOptions {
+  maxClasses?: number;
+  maxOuterHTMLLength?: number;
+  maxInnerTextLength?: number;
+}
+
+/**
+ * Builds a clean, human-readable semantic selector for a DOM element.
+ * Prioritizes data-testid/data-test, id, semantic tag + specific class, or concise parent path.
+ */
+export function getSemanticSelector(element: HTMLElement | Element, options: SelectorOptions = {}): string {
+  if (!element || !element.tagName) return 'unknown';
+
+  const maxClasses = options.maxClasses ?? 2;
+
+  // 1. Check for standard test attributes
+  const testId =
+    element.getAttribute('data-testid') ||
+    element.getAttribute('data-test') ||
+    element.getAttribute('data-cy') ||
+    element.getAttribute('data-qa');
+
+  if (testId) {
+    return `[data-testid="${testId}"]`;
+  }
+
+  // 2. Check for meaningful ID (skip dynamic UUID/numeric IDs)
+  const id = element.id;
+  if (id && !/^[0-9]+$/.test(id) && !/[0-9a-f]{8}-[0-9a-f]{4}/i.test(id)) {
+    return `#${id}`;
+  }
+
+  // 3. Check for aria-label or name on buttons/inputs
+  const ariaLabel = element.getAttribute('aria-label');
+  if (ariaLabel && ariaLabel.length < 30) {
+    return `${element.tagName.toLowerCase()}[aria-label="${ariaLabel}"]`;
+  }
+
+  const nameAttr = element.getAttribute('name');
+  if (nameAttr) {
+    return `${element.tagName.toLowerCase()}[name="${nameAttr}"]`;
+  }
+
+  // 4. Tag + curated classes
+  const tag = element.tagName.toLowerCase();
+  const classList = Array.from(element.classList || [])
+    .filter((c) => !c.startsWith('css-') && !c.startsWith('_') && !/^[a-z0-9]{5,}$/i.test(c)) // filter hashed utility classes
+    .slice(0, maxClasses);
+
+  if (classList.length > 0) {
+    const classStr = classList.map((c) => `.${c}`).join('');
+    return `${tag}${classStr}`;
+  }
+
+  // 5. If generic element (div, span, p) without attributes, try parent context
+  if (element.parentElement && element.parentElement !== document.body && element.parentElement !== document.documentElement) {
+    const parentSelector = getSemanticSelector(element.parentElement, { maxClasses: 1 });
+    if (parentSelector && parentSelector !== 'unknown' && !parentSelector.includes('>')) {
+      return `${parentSelector} > ${tag}`;
+    }
+  }
+
+  return tag;
+}
+
+/**
+ * Truncates string to specified max length with ellipsis
+ */
+export function truncate(str: string | undefined | null, maxLength = 200): string {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + '...';
+}

package/packages/core/src/types/commands.ts

@@ -0,0 +1,101 @@
+import type { ElementSummary } from './events.js';
+
+export type CommandType =
+  | 'reload'
+  | 'navigate'
+  | 'get_page_state'
+  | 'query_element'
+  | 'capture_element'
+  | 'check_overflow'
+  | 'get_element_rect'
+  | 'get_element_style';
+
+export interface ClientCommand<T = any> {
+  id: string;
+  type: CommandType;
+  params?: T;
+}
+
+export interface ReloadParams {
+  force?: boolean;
+}
+
+export interface NavigateParams {
+  url: string;
+}
+
+export interface QueryElementParams {
+  selector: string;
+}
+
+export interface CaptureElementParams {
+  selector?: string;
+}
+
+export interface QueryElementResult {
+  exists: boolean;
+  visible?: boolean;
+  tag?: string;
+  id?: string;
+  classes?: string[];
+  boundingRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+  };
+  innerText?: string;
+  outerHTML?: string;
+}
+
+export interface PageStateResult {
+  url: string;
+  route: string;
+  title: string;
+  readyState: string;
+  activeElement?: ElementSummary;
+}
+
+export interface CaptureElementResult {
+  dataUrl?: string;
+  format?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface OverflowCheckResult {
+  selector: string;
+  overflow: boolean;
+  viewportWidth: number;
+  viewportHeight: number;
+  rect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+  };
+  overflowRightPx: number;
+  overflowBottomPx: number;
+  parentOverflow?: boolean;
+}
+
+export interface ElementStyleResult {
+  selector: string;
+  styles: Record<string, string>;
+}
+
+export interface CommandResponse<T = any> {
+  id: string;
+  ok: boolean;
+  result?: T;
+  error?: string;
+  reason?: string;
+}