browsertrack 0.0.1 → 0.1.1

package/packages/core/src/redaction.ts

@@ -0,0 +1,174 @@
+import { redact as visulimaRedact, standardRules, type Rules } from '@visulima/redact';
+
+/**
+ * Security and Redaction Utilities powered by @visulima/redact
+ */
+
+export const REDACTED_PLACEHOLDER = '[REDACTED]';
+
+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',
+];
+
+/**
+ * Developer security rules for @visulima/redact
+ */
+export const BROWSER_SECURITY_RULES: Rules = [
+  { deep: true, key: 'password', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'secret', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'token', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'authorization', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'cookie', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'set-cookie', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'apikey', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'api_key', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'creditcard', pattern: /(?:\d[ -]*?){13,16}/, replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'cvv', replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/, replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'awsid', pattern: /\bAKIA[0-9A-Z]{16}\b/, replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'awskey', pattern: /\b[0-9a-zA-Z/+]{40}\b/, replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'jwt', pattern: /\beyJ[0-9a-zA-Z_\-]*\.[0-9a-zA-Z_\-]*\.[0-9a-zA-Z_\-]*\b/, replacement: REDACTED_PLACEHOLDER },
+  { deep: true, key: 'slack_token', pattern: /\bxox[baprs]-[0-9a-zA-Z]{10,48}\b/, replacement: REDACTED_PLACEHOLDER },
+];
+
+export { visulimaRedact, standardRules };
+export type { Rules };
+
+/**
+ * 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 and payload data from an object or array,
+ * leveraging @visulima/redact rules combined with BrowserTrack URL/header sanitizers.
+ */
+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 {
+        try {
+          result[key] = visulimaRedact(value, BROWSER_SECURITY_RULES);
+        } catch {
+          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;
+}

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

@@ -0,0 +1,108 @@
+export type EventType =
+  | 'runtime_error'
+  | 'unhandled_rejection'
+  | 'console'
+  | 'fetch'
+  | 'xhr'
+  | 'navigation'
+  | 'interaction';
+
+export type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
+
+export interface ElementSummary {
+  selector: string;
+  tag: string;
+  id?: string;
+  classes?: string[];
+  attributes?: Record<string, string>;
+  outerHTML?: string;
+  innerText?: string;
+  boundingRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+  };
+  visible: boolean;
+}
+
+export interface Breadcrumb {
+  id?: string;
+  type: 'navigation' | 'click' | 'submit' | 'fetch' | 'xhr' | 'console' | 'error';
+  category?: string;
+  message: string;
+  timestamp: number;
+  level?: 'info' | 'warn' | 'error';
+  data?: Record<string, any>;
+  element?: ElementSummary;
+}
+
+export interface NetworkEvent {
+  id?: string;
+  url: string;
+  method: string;
+  status?: number;
+  statusText?: string;
+  durationMs: number;
+  error?: string;
+  aborted?: boolean;
+  timestamp: number;
+  requestHeaders?: Record<string, string>;
+}
+
+export interface RuntimeErrorEvent {
+  message: string;
+  stack?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+  errorType: string;
+  timestamp: number;
+}
+
+export interface ConsoleEvent {
+  level: ConsoleLevel;
+  message: string;
+  args?: any[];
+  stack?: string;
+  timestamp: number;
+}
+
+export interface NavigationEvent {
+  from?: string;
+  to: string;
+  type: 'pushState' | 'replaceState' | 'popstate' | 'hashchange' | 'initial';
+  timestamp: number;
+}
+
+export interface HelloMessage {
+  type: 'hello';
+  origin: string;
+  url: string;
+  title: string;
+  userAgent: string;
+  timestamp: number;
+  projectId?: string;
+}
+
+export interface ClientEventMessage {
+  type: 'event';
+  sessionId: string;
+  eventType: EventType;
+  payload:
+    | RuntimeErrorEvent
+    | ConsoleEvent
+    | NetworkEvent
+    | NavigationEvent
+    | Breadcrumb;
+  breadcrumbs?: Breadcrumb[];
+  lastElement?: ElementSummary;
+  route?: string;
+  url: string;
+  title?: string;
+  timestamp: number;
+}

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

@@ -0,0 +1,54 @@
+import type { Breadcrumb, ElementSummary, NetworkEvent } from './events.js';
+
+export type IncidentStatus =
+  | 'OPEN'
+  | 'FIX_ATTEMPTED'
+  | 'VERIFYING'
+  | 'VERIFIED'
+  | 'FAILED'
+  | 'INCONCLUSIVE';
+
+export type IncidentSeverity = 'error' | 'warn' | 'fatal';
+
+export interface IncidentSource {
+  file: string;
+  line: number;
+  column?: number;
+}
+
+export interface Incident {
+  id: string;
+  projectId: string;
+  sessionId: string;
+  type: string;
+  severity: IncidentSeverity;
+  message: string;
+  source: IncidentSource;
+  fingerprint: string;
+  route: string;
+  firstSeen: string;
+  lastSeen: string;
+  occurrences: number;
+  status: IncidentStatus;
+  stack?: string;
+  breadcrumbs: Breadcrumb[];
+  networkFailures: NetworkEvent[];
+  lastElement?: ElementSummary;
+  screenshots?: {
+    error?: string;
+    before?: string;
+    after?: string;
+  };
+}
+
+export interface IncidentOccurrence {
+  id: string;
+  incidentId: string;
+  sessionId: string;
+  timestamp: string;
+  route: string;
+  url: string;
+  stack?: string;
+  breadcrumbs: Breadcrumb[];
+  lastElement?: ElementSummary;
+}

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

@@ -0,0 +1,106 @@
+export type NoteType = 'element' | 'region' | 'page';
+
+export type NoteStatus =
+  | 'OPEN'
+  | 'IN_PROGRESS'
+  | 'VERIFYING'
+  | 'READY_FOR_REVIEW'
+  | 'VERIFIED'
+  | 'RESOLVED'
+  | 'FAILED'
+  | 'INCONCLUSIVE';
+
+export interface ViewportContext {
+  width: number;
+  height: number;
+  devicePixelRatio: number;
+}
+
+export interface ScrollContext {
+  scrollX: number;
+  scrollY: number;
+}
+
+export interface DOMRectJson {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
+export interface NoteTarget {
+  selector: string;
+  boundingRect: DOMRectJson;
+  visible: boolean;
+  confidence?: 'high' | 'medium' | 'low';
+}
+
+export interface ElementContext {
+  selector: string;
+  tag: string;
+  attributes?: Record<string, string>;
+  outerHTML?: string;
+  innerText?: string;
+  parent?: {
+    selector: string;
+    tag: string;
+  };
+}
+
+export interface RegionContext {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface VisualNote {
+  id: string;
+  projectId: string;
+  sessionId: string;
+  type: NoteType;
+  message: string;
+  route: string;
+  url: string;
+  viewport: ViewportContext;
+  scroll: ScrollContext;
+  target?: NoteTarget;
+  elementContext?: ElementContext;
+  region?: RegionContext;
+  status: NoteStatus;
+  incidentId?: string;
+  screenshots?: {
+    original?: string;
+    after?: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+  resolvedAt?: string;
+}
+
+export interface NoteVerificationResult {
+  noteId: string;
+  status: NoteStatus;
+  checks: Array<{
+    type: string;
+    passed: boolean;
+    details?: string;
+  }>;
+  geometryDiff?: {
+    before?: DOMRectJson;
+    current?: DOMRectJson;
+    viewportWidth?: number;
+    overflowFixed?: boolean;
+    overflowPx?: number;
+  };
+  screenshots?: {
+    before?: string;
+    after?: string;
+  };
+  timestamp: string;
+  message?: string;
+}

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

@@ -0,0 +1,44 @@
+import type { IncidentStatus } from './incidents.js';
+
+export type ProbeType =
+  | 'element_exists'
+  | 'element_visible'
+  | 'text_contains'
+  | 'route_is'
+  | 'network_request_succeeded'
+  | 'no_incident';
+
+export interface VerificationProbe {
+  type: ProbeType;
+  selector?: string;
+  text?: string;
+  route?: string;
+  fingerprint?: string;
+  urlPattern?: string;
+  timeoutMs?: number;
+}
+
+export interface VerificationRecipe {
+  route?: string;
+  targetSelector?: string;
+  expect?: VerificationProbe[];
+  observationWindowMs?: number;
+}
+
+export interface ProbeResult {
+  type: ProbeType;
+  passed: boolean;
+  details?: string;
+}
+
+export interface VerificationResult {
+  incidentId: string;
+  status: IncidentStatus;
+  checks: ProbeResult[];
+  screenshots?: {
+    before?: string;
+    after?: string;
+  };
+  timestamp: string;
+  message?: string;
+}

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

@@ -0,0 +1,20 @@
+export interface Project {
+  id: string;
+  name: string;
+  origin: string;
+  path?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Session {
+  id: string;
+  projectId: string;
+  origin: string;
+  url: string;
+  title: string;
+  userAgent: string;
+  connectedAt: string;
+  lastSeenAt: string;
+  active: boolean;
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}