@hanzo/event 0.3.0 → 0.3.2

package/src/index.ts

@@ -8,6 +8,9 @@
 // React apps use the './react' entry for the provider + hooks + error boundary.
 
 export { Analytics, createAnalytics, VERSION, getCohort, getFirstTouch } from './core'
+export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
+export type { ErrorIdentity } from './sentry'
+export { scrubText, redactSecrets, scrubPII } from './scrub'
 export { EVENTS, PAGEVIEW } from './events'
 export type { EventName } from './events'
 export { GOALS, COHORTS } from './goals'
@@ -22,9 +25,14 @@ export {
 export type {
   AnalyticsConfig,
   Attribution,
+  CaptureErrorOptions,
   Cohort,
+  Dsn,
   EventKind,
   Exception,
+  SentryEvent,
+  SentryFrame,
+  SentryLevel,
   Transport,
   WireEvent,
 } from './types'

package/src/scrub.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest'
+import { redactSecrets, scrubPII, scrubText, MAX_SCRUB_LEN } from './scrub'
+
+describe('redactSecrets (always applied)', () => {
+  it('redacts a hanzo key', () => {
+    expect(redactSecrets('key=hk-ABCDEFGHIJKLMNOP1234 tail')).toContain('[redacted]')
+    expect(redactSecrets('key=hk-ABCDEFGHIJKLMNOP1234 tail')).not.toContain('hk-ABCDEFGHIJKLMNOP1234')
+  })
+  it('redacts a JWT', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.abcdefghij'
+    expect(redactSecrets(`token ${jwt}`)).not.toContain(jwt)
+  })
+  it('redacts a bearer token', () => {
+    expect(redactSecrets('Authorization: Bearer abcdef0123456789ABCDEF')).toContain('[redacted]')
+  })
+  it('redacts openai/stripe/aws/github/google/slack shapes', () => {
+    expect(redactSecrets('sk-proj-ABCDEFGHIJKLMNOPQRST')).toContain('[redacted]')
+    expect(redactSecrets('sk_live_ABCDEFGHIJKLMNOP1234')).toContain('[redacted]')
+    expect(redactSecrets('AKIAABCDEFGHIJKLMNOP')).toContain('[redacted]')
+    expect(redactSecrets('ghp_ABCDEFGHIJKLMNOPQRSTUVWX')).toContain('[redacted]')
+    expect(redactSecrets('AIzaABCDEFGHIJKLMNOPQRSTUVWXYZ012345')).toContain('[redacted]')
+    expect(redactSecrets('xoxb-1111-2222-abcdefghij')).toContain('[redacted]')
+  })
+  it('redacts credentials embedded in a URL/DSN', () => {
+    expect(redactSecrets('postgres://user:s3cretpw@db.host:5432/x')).toContain('[redacted]')
+    expect(redactSecrets('postgres://user:s3cretpw@db.host:5432/x')).not.toContain('s3cretpw')
+  })
+})
+
+describe('scrubPII (default; opt-out via capturePII)', () => {
+  it('masks emails and IPs', () => {
+    expect(scrubPII('from alice@example.com at 192.168.1.7')).toBe('from [email] at [ip]')
+  })
+  it('scrubText masks by default and retains when capturePII=true', () => {
+    expect(scrubText('alice@example.com', false)).toBe('[email]')
+    expect(scrubText('alice@example.com', true)).toBe('alice@example.com')
+  })
+  it('scrubText still redacts secrets even when capturePII=true', () => {
+    expect(scrubText('hk-ABCDEFGHIJKLMNOP1234', true)).toContain('[redacted]')
+  })
+  it('is total on empty/undefined', () => {
+    expect(scrubText(undefined)).toBe('')
+    expect(scrubText('')).toBe('')
+  })
+})
+
+// ── denial of service ──────────────────────────────────────────────────────
+//
+// The scrubber runs SYNCHRONOUSLY on the main thread inside captureError, and its
+// input is attacker-influenced: `throw new Error(await res.text())` against an
+// HTML error page is a one-line way to hand it 128KB. The creds-in-URL pattern
+// backtracked quadratically on colon-rich text with no terminating '@' — 4.9s at
+// 32KB, >60s at 128KB. Both the input cap and the bounded pattern are load-bearing.
+
+describe('input bounding', () => {
+  it('caps input length and says so', () => {
+    const out = scrubText('a'.repeat(MAX_SCRUB_LEN * 4))
+    expect(out.length).toBeLessThan(MAX_SCRUB_LEN + 64)
+    expect(out.endsWith('… [truncated]')).toBe(true)
+  })
+
+  it('scrubs pathological colon-rich input in bounded time', () => {
+    // The exact shape that blew up: many colons, no '@' to terminate the match.
+    const hostile = '<div class="a:b:c">'.repeat(8000) // ~150KB
+    const t0 = Date.now()
+    const out = scrubText(hostile)
+    const ms = Date.now() - t0
+    expect(out).toBeTruthy()
+    // Was >60s unbounded. Generous ceiling so the test is not flaky on slow CI.
+    expect(ms).toBeLessThan(1000)
+  })
+
+  it('still redacts real credentials in a URL', () => {
+    expect(scrubText('postgres://user:hunter2@db.internal/app')).toContain('[redacted]')
+    expect(scrubText('postgres://user:hunter2@db.internal/app')).not.toContain('hunter2')
+  })
+})
+
+// ── PAN false positives ────────────────────────────────────────────────────
+//
+// The bare digit-run rule redacted every millisecond epoch and order id it saw,
+// destroying the readability of the messages this client exists to deliver. It is
+// now gated on Luhn, which every real card satisfies — so the false positives go
+// away without introducing a false negative.
+
+describe('card numbers', () => {
+  it('redacts a real (Luhn-valid) card number', () => {
+    expect(scrubText('card 4111111111111111 declined')).toContain('[redacted]')
+    expect(scrubText('card 4111-1111-1111-1111 declined')).toContain('[redacted]')
+  })
+
+  it('leaves an epoch timestamp alone', () => {
+    const out = scrubText('request 1753468800000 timed out')
+    expect(out).toBe('request 1753468800000 timed out')
+  })
+})

package/src/scrub.ts

@@ -0,0 +1,112 @@
+// Client-side redaction for error text — a faithful port of the server's
+// errortracking scrub (o11y pkg/modules/errortracking/implerrortracking/scrub.go),
+// applied BEFORE anything leaves the browser. Two layers, default-secure:
+//
+//   - Secret shapes are ALWAYS redacted (sk-… keys, bearer/JWT tokens, DB DSNs,
+//     PANs, cloud keys). There is no mode that ships a secret off-device.
+//   - PII (email/IP) is scrubbed UNLESS capturePII is explicitly enabled.
+//
+// The server scrubs again — this is defense in depth, not a substitute — but the
+// point is that a Hanzo browser never emits a raw secret/email/IP in the first
+// place. Pure, no I/O.
+
+const REDACTED = '[redacted]'
+const EMAIL_MARK = '[email]'
+const IP_MARK = '[ip]'
+
+// Secret patterns mirror scrub.go's secretPatterns. Order matters (broad DSN/PAN
+// rules run last). All are applied unconditionally.
+const SECRET_PATTERNS: RegExp[] = [
+  /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----/g,
+  /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, // JWT
+  /\bbearer\s+[A-Za-z0-9._~+/-]{12,}=*/gi, // bearer token
+  /\b(?:sk|pk|rk)-[A-Za-z0-9]{2,}-?[A-Za-z0-9]{12,}/g, // openai-style
+  /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{16,}/g, // stripe
+  /\bhk-[A-Za-z0-9]{16,}/g, // hanzo key
+  /\bAKIA[0-9A-Z]{16}\b/g, // aws access key id
+  /\bASIA[0-9A-Z]{16}\b/g, // aws sts key id
+  /\bAIza[0-9A-Za-z_-]{20,}/g, // google api key
+  /\bgh[posru]_[A-Za-z0-9]{20,}/g, // github token
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/g, // slack token
+  // Creds in a URL/DSN. The repetition is BOUNDED on purpose: the unbounded form
+  // ([^\s:@/]+:[^\s@/]+@) backtracks quadratically on colon-rich text with no
+  // terminating '@' — an HTML error page pasted into an error message took 4.9s
+  // at 32KB and >60s at 128KB, freezing the main thread from inside captureError.
+  // Real userinfo is far below these caps, so bounding costs nothing.
+  /[a-zA-Z][a-zA-Z0-9+.-]{0,32}:\/\/[^\s:@/]{1,256}:[^\s@/]{1,256}@/g,
+]
+
+/** Candidate card numbers. Gated by Luhn below — the bare digit-run pattern is a
+ *  false-positive cannon that redacts every millisecond epoch, order id and
+ *  phone number it sees ("request 1753468800000 timed out" became
+ *  "request [redacted]timed out"), which destroys the readability of the very
+ *  error messages this client exists to deliver. */
+const RE_PAN = /\b(?:\d[ -]?){13,19}\b/g
+
+/** luhn reports whether a digit string satisfies the Luhn checksum. Every real
+ *  card number does, so gating redaction on it removes the false positives
+ *  WITHOUT introducing a false negative — the safe direction for a redactor. */
+function luhn(digits: string): boolean {
+  let sum = 0
+  let alt = false
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let d = digits.charCodeAt(i) - 48
+    if (alt) {
+      d *= 2
+      if (d > 9) d -= 9
+    }
+    sum += d
+    alt = !alt
+  }
+  return sum % 10 === 0
+}
+
+/** redactPAN removes digit runs that actually check out as card numbers. */
+function redactPAN(s: string): string {
+  return s.replace(RE_PAN, (m) => {
+    const digits = m.replace(/[ -]/g, '')
+    if (digits.length < 13 || digits.length > 19) return m
+    return luhn(digits) ? REDACTED : m
+  })
+}
+
+const RE_EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g
+const RE_IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g
+const RE_IPV6 = /\b(?:[0-9A-Fa-f]{1,4}:){2,7}[0-9A-Fa-f]{1,4}\b/g
+
+/** redactSecrets removes known secret shapes. Always applied. */
+export function redactSecrets(s: string): string {
+  for (const re of SECRET_PATTERNS) s = s.replace(re, REDACTED)
+  return redactPAN(s)
+}
+
+/** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
+export function scrubPII(s: string): string {
+  s = s.replace(RE_EMAIL, EMAIL_MARK)
+  s = s.replace(RE_IPV6, IP_MARK)
+  s = s.replace(RE_IPV4, IP_MARK)
+  return s
+}
+
+/** Longest free-text field this module will scrub. Every pattern here is a regex
+ *  run synchronously on the main thread, and the input is attacker-influenced —
+ *  `throw new Error(await res.text())` against an HTML error page is a one-line
+ *  way to hand us 128KB. Bounding the INPUT bounds the work regardless of which
+ *  pattern is pathological. 8KB is far beyond any real error message. */
+export const MAX_SCRUB_LEN = 8192
+
+/** truncate caps a string at MAX_SCRUB_LEN, marking that it was cut so a reader
+ *  never mistakes a truncated message for the whole one. */
+export function truncate(s: string, max = MAX_SCRUB_LEN): string {
+  return s.length > max ? s.slice(0, max) + '… [truncated]' : s
+}
+
+/** scrubText applies the redaction policy to a free-text field. Input is capped
+ *  first: unbounded text is a denial-of-service surface, not just a size problem. */
+export function scrubText(s: string | undefined, capturePII = false): string {
+  if (!s) return s ?? ''
+  s = truncate(s)
+  s = redactSecrets(s)
+  if (!capturePII) s = scrubPII(s)
+  return s
+}

package/src/sentry.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from 'vitest'
+import { createHash } from 'node:crypto'
+import {
+  parseDsn,
+  framesFromStack,
+  buildSentryEvent,
+  buildEnvelope,
+  eventId,
+  normalizeError,
+} from './sentry'
+import type { SentryEvent, SentryFrame } from './types'
+import { VERSION } from './version'
+
+const DSN = 'https://1:deadbeefcafe@api.hanzo.ai/v1/sentry/00000000-0000-0000-0000-000000000000'
+
+describe('parseDsn', () => {
+  it('keeps the version:hmac key intact (does NOT split on the colon) and derives the ingest url', () => {
+    const dsn = parseDsn(DSN)!
+    expect(dsn.publicKey).toBe('1:deadbeefcafe')
+    expect(dsn.origin).toBe('https://api.hanzo.ai')
+    expect(dsn.projectId).toBe('00000000-0000-0000-0000-000000000000')
+    expect(dsn.ingestUrl).toBe(
+      'https://api.hanzo.ai/v1/sentry/00000000-0000-0000-0000-000000000000/envelope/?sentry_key=1%3Adeadbeefcafe',
+    )
+  })
+  it('returns null for malformed input (fail-safe)', () => {
+    expect(parseDsn(undefined)).toBeNull()
+    expect(parseDsn('')).toBeNull()
+    expect(parseDsn('not-a-dsn')).toBeNull()
+    expect(parseDsn('https://api.hanzo.ai/v1/sentry/x')).toBeNull() // no key
+    expect(parseDsn('https://1:k@api.hanzo.ai')).toBeNull() // no project
+  })
+})
+
+describe('framesFromStack', () => {
+  it('parses a V8 stack oldest-first with in_app marking', () => {
+    const stack = [
+      'TypeError: x is not a function',
+      '    at inner (https://app.hanzo.ai/app.js:10:5)',
+      '    at outer (https://app.hanzo.ai/app.js:20:1)',
+      '    at eval (webpack-internal:///./node_modules/lib/index.js:3:2)',
+    ].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(3)
+    // oldest-first: the node_modules frame is the outermost caller (first),
+    // the crash site (inner) is last.
+    expect(frames[frames.length - 1].function).toBe('inner')
+    expect(frames[frames.length - 1].lineno).toBe(10)
+    expect(frames[frames.length - 1].in_app).toBe(true)
+    expect(frames[0].function).toBe('eval')
+    expect(frames[0].in_app).toBe(false) // node_modules
+  })
+  it('parses a Firefox/Safari stack (fn@file:li:co and bare @file)', () => {
+    const stack = ['boom@https://app.hanzo.ai/a.js:1:2', '@https://app.hanzo.ai/b.js:3:4'].join('\n')
+    const frames = framesFromStack(stack)
+    expect(frames).toHaveLength(2)
+    expect(frames[frames.length - 1].function).toBe('boom')
+    expect(frames[frames.length - 1].filename).toBe('https://app.hanzo.ai/a.js')
+  })
+  it('skips the header line and tolerates junk', () => {
+    expect(framesFromStack('Error: nope\n   total garbage line')).toHaveLength(0)
+    expect(framesFromStack(undefined)).toHaveLength(0)
+  })
+})
+
+describe('normalizeError', () => {
+  it('coerces Error, string, and objects', () => {
+    expect(normalizeError(new RangeError('r')).name).toBe('RangeError')
+    expect(normalizeError('boom')).toEqual({ name: 'Error', message: 'boom' })
+    expect(normalizeError({ a: 1 }).message).toBe('{"a":1}')
+  })
+})
+
+describe('eventId', () => {
+  it('is 32 lowercase hex chars (the Sentry event_id shape)', () => {
+    expect(eventId()).toMatch(/^[0-9a-f]{32}$/)
+    expect(eventId()).not.toBe(eventId())
+  })
+})
+
+describe('buildSentryEvent', () => {
+  it('sets subject-only user, default error level, scrubbed message, product tags', () => {
+    const ev = buildSentryEvent({
+      error: new Error('boom for bob@corp.com'),
+      identity: { userId: 'sub-9', sessionId: 'sess-1', product: 'app', release: 'v1', environment: 'production' },
+    })
+    expect(ev.platform).toBe('javascript')
+    expect(ev.level).toBe('error')
+    expect(ev.user).toEqual({ id: 'sub-9' })
+    expect(ev.exception!.values[0].value).toBe('boom for [email]')
+    expect(ev.tags!.product).toBe('app')
+    expect(ev.tags!.session).toBe('sess-1')
+    expect(ev.tags!.handled).toBe('true')
+    expect(ev.release).toBe('v1')
+    expect(ev.environment).toBe('production')
+    expect(ev.sdk).toEqual({ name: '@hanzo/event', version: VERSION })
+  })
+  it('uncaught errors default to fatal level and handled=false', () => {
+    const ev = buildSentryEvent({ error: new Error('x'), options: { handled: false }, identity: {} })
+    expect(ev.level).toBe('fatal')
+    expect(ev.tags!.handled).toBe('false')
+  })
+  it('omits user entirely when there is no subject', () => {
+    const ev = buildSentryEvent({ error: new Error('x'), identity: {} })
+    expect(ev.user).toBeUndefined()
+  })
+})
+
+// ── round-trip proof: a byte-faithful TS port of the SERVER parser recovers the
+//    exact event from our envelope. Port of o11y
+//    pkg/modules/errortracking/implerrortracking/envelope.go parseEnvelope. ───────
+
+function parseEnvelopeOracle(body: Uint8Array): SentryEvent[] {
+  let pos = 0
+  const dec = new TextDecoder()
+  const readLine = (): Uint8Array | null => {
+    if (pos >= body.length) return null
+    const nl = body.indexOf(0x0a, pos)
+    if (nl >= 0) {
+      const line = body.subarray(pos, nl)
+      pos = nl + 1
+      return line
+    }
+    const line = body.subarray(pos)
+    pos = body.length
+    return line
+  }
+  if (readLine() === null) throw new Error('empty envelope') // required header
+  const events: SentryEvent[] = []
+  while (pos < body.length) {
+    if (events.length >= 1000) break
+    const hdrLine = readLine()
+    if (hdrLine === null) break
+    const hdrStr = dec.decode(hdrLine).trim()
+    if (hdrStr.length === 0) continue
+    let ih: { type?: string; length?: number | null }
+    try {
+      ih = JSON.parse(hdrStr)
+    } catch {
+      break
+    }
+    let payload: Uint8Array | null
+    if (ih.length != null && ih.length >= 0 && ih.length <= body.length - pos) {
+      const end = pos + ih.length
+      payload = body.subarray(pos, end)
+      pos = end
+      if (pos < body.length && body[pos] === 0x0a) pos++
+    } else {
+      payload = readLine()
+      if (payload === null) break
+    }
+    if (ih.type === 'event') {
+      try {
+        events.push(JSON.parse(dec.decode(payload)) as SentryEvent)
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  return events
+}
+
+describe('buildEnvelope round-trip (server parser recovers our event)', () => {
+  it('recovers exactly one event with matching id + exception', () => {
+    const dsn = parseDsn(DSN)!
+    const event = buildSentryEvent({
+      error: new TypeError('cannot read properties of undefined'),
+      identity: { userId: 'sub-1', sessionId: 'sess-1', product: 'app' },
+    })
+    const envelope = buildEnvelope(event, dsn)
+    const recovered = parseEnvelopeOracle(new TextEncoder().encode(envelope))
+    expect(recovered).toHaveLength(1)
+    expect(recovered[0].event_id).toBe(event.event_id)
+    expect(recovered[0].exception!.values[0].type).toBe('TypeError')
+    expect(recovered[0].platform).toBe('javascript')
+  })
+
+  it('byte-length framing is correct with multi-byte characters', () => {
+    const dsn = parseDsn(DSN)!
+    const event = buildSentryEvent({
+      error: new Error('naïve café €500 — 日本語 fails'),
+      identity: { userId: 'sub-1' },
+    })
+    const envelope = buildEnvelope(event, dsn)
+    const recovered = parseEnvelopeOracle(new TextEncoder().encode(envelope))
+    expect(recovered).toHaveLength(1)
+    expect(recovered[0].exception!.values[0].value).toContain('日本語')
+  })
+})
+
+// ── grouping proof: a compact port of the server fingerprint (fingerprint.go).
+//    Two errors with the same crash frame group together; a different type does not.
+
+function normalizeFunction(fn: string): string {
+  return fn.replace(/0x[0-9a-fA-F]+/g, '').trim()
+}
+function normalizeFilename(name: string): string {
+  name = name.trim().replace(/\\/g, '/')
+  const i = name.search(/[?#]/)
+  if (i >= 0) name = name.slice(0, i)
+  let segs = name.replace(/^\/+|\/+$/g, '').split('/')
+  if (segs.length > 2) segs = segs.slice(segs.length - 2)
+  return segs.map((s) => s.replace(/\b[0-9a-fA-F]{8,}\b/g, '*').replace(/\b\d[\d.,_]*\b/g, '*')).join('/')
+}
+function normalizeFrame(f: SentryFrame): string {
+  const fn = normalizeFunction(f.function ?? '')
+  const loc = f.module || normalizeFilename(f.filename ?? '') || normalizeFilename(f.abs_path ?? '')
+  if (fn && loc) return `${fn}@${loc}`
+  return fn || loc
+}
+function pickCrashFrame(frames: SentryFrame[]): SentryFrame | null {
+  if (frames.length === 0) return null
+  for (let i = frames.length - 1; i >= 0; i--) if (frames[i].in_app) return frames[i]
+  return frames[frames.length - 1]
+}
+function fingerprintOf(ev: SentryEvent): string {
+  const val = ev.exception!.values[0]
+  const parts: string[] = []
+  if (val.type) parts.push('type:' + val.type)
+  const frame = pickCrashFrame(val.stacktrace?.frames ?? [])
+  if (frame) {
+    const sig = normalizeFrame(frame)
+    if (sig) parts.push('frame:' + sig)
+  }
+  const h = createHash('sha256')
+  parts.forEach((p, i) => {
+    if (i > 0) h.update(Buffer.from([0]))
+    h.update(Buffer.from(p, 'utf8'))
+  })
+  return h.digest('hex')
+}
+
+describe('fingerprint grouping (port of server model)', () => {
+  const stack = [
+    'TypeError: user missing',
+    '    at loadUser (https://app.hanzo.ai/app.9f3a2b1c.js:42:11)',
+    '    at render (https://app.hanzo.ai/app.9f3a2b1c.js:88:3)',
+  ].join('\n')
+
+  it('groups two errors with the same crash frame despite different ids in the message', () => {
+    const e1 = new Error('user 111 missing')
+    e1.stack = stack.replace('user missing', 'user 111 missing')
+    const e2 = new Error('user 222 missing')
+    e2.stack = stack.replace('user missing', 'user 222 missing')
+    const f1 = fingerprintOf(buildSentryEvent({ error: e1, identity: {} }))
+    const f2 = fingerprintOf(buildSentryEvent({ error: e2, identity: {} }))
+    expect(f1).toMatch(/^[0-9a-f]{64}$/)
+    expect(f1).toBe(f2)
+  })
+
+  it('does NOT group different exception types', () => {
+    const e1 = new TypeError('boom')
+    e1.stack = stack
+    const e2 = new RangeError('boom')
+    e2.stack = stack.replace('TypeError', 'RangeError')
+    const f1 = fingerprintOf(buildSentryEvent({ error: e1, identity: {} }))
+    const f2 = fingerprintOf(buildSentryEvent({ error: e2, identity: {} }))
+    expect(f1).not.toBe(f2)
+  })
+})