@vyro-x/sentry 0.1.0

package/src/nextjs.ts

@@ -0,0 +1,48 @@
+import * as Sentry from '@sentry/nextjs'
+import { DEFAULT_TRACES_SAMPLE_RATE, resolveEnvironment } from './config'
+import type { SentryScrubOptions } from './scrub'
+import { createSentryScrubbers } from './scrubbers'
+
+/** Re-exported SDK, for the rare escape hatch. Prefer the helper below. */
+export { Sentry }
+export const captureException = Sentry.captureException
+
+/**
+ * Options for `initSentry`. Used by all three Next.js runtimes
+ * (`sentry.server.config.ts`, `sentry.client.config.ts`, `sentry.edge.config.ts`).
+ */
+export interface NextSentryInitOptions {
+  /** DSN; defaults to `process.env.NEXT_PUBLIC_SENTRY_DSN` then `process.env.SENTRY_DSN`. */
+  dsn?: string
+  /** Logical name shown as `server_name` (server/edge runtimes). */
+  serverName?: string
+  /** Performance tracing sample rate. Defaults to `0.2`. */
+  tracesSampleRate?: number
+  /** Overrides the resolved `environment`. */
+  environment?: string
+  /** Scrubber options (extra keys/patterns, placeholder, …). */
+  scrub?: SentryScrubOptions
+  /** Extra `@sentry/nextjs` init options, merged last so they can override defaults. */
+  init?: Parameters<typeof Sentry.init>[0]
+}
+
+/**
+ * Initialises `@sentry/nextjs` (server, client or edge) for the Vyro website with
+ * secret-scrubbing already wired in. Idempotent and a no-op when no DSN is configured.
+ */
+export function initSentry(options: NextSentryInitOptions = {}): void {
+  const dsn =
+    options.dsn ??
+    (typeof process !== 'undefined'
+      ? (process.env.NEXT_PUBLIC_SENTRY_DSN ?? process.env.SENTRY_DSN)
+      : undefined)
+  if (!dsn) return
+  Sentry.init({
+    ...createSentryScrubbers(options.scrub),
+    dsn,
+    serverName: options.serverName,
+    environment: options.environment ?? resolveEnvironment(),
+    tracesSampleRate: options.tracesSampleRate ?? DEFAULT_TRACES_SAMPLE_RATE,
+    ...options.init,
+  })
+}

package/src/node.ts

@@ -0,0 +1,81 @@
+import * as Sentry from '@sentry/node'
+import { DEFAULT_TRACES_SAMPLE_RATE, resolveEnvironment } from './config'
+import type { SentryScrubOptions } from './scrub'
+import { createSentryScrubbers } from './scrubbers'
+
+/** Re-exported SDK, for the rare escape hatch. Prefer the helpers below. */
+export { Sentry }
+/**
+ * Express error handler (Sentry v8+). Call after your routes are registered so
+ * errors bubbling out of the app are reported. Replaces the removed
+ * `Sentry.Handlers.errorHandler()`.
+ */
+export const setupExpressErrorHandler = Sentry.setupExpressErrorHandler
+
+let initialised = false
+
+export interface NodeSentryInitOptions {
+  /** Logical service name — shown in Sentry as `server_name`. */
+  serverName: string
+  /** DSN; defaults to `process.env.SENTRY_DSN`. When absent, init is skipped. */
+  dsn?: string
+  /** Performance tracing sample rate. Defaults to `0.2`. */
+  tracesSampleRate?: number
+  /** Overrides the resolved `environment`. */
+  environment?: string
+  /** Scrubber options (extra keys/patterns, placeholder, …). */
+  scrub?: SentryScrubOptions
+  /** Extra `@sentry/node` init options, merged last so they can override defaults. */
+  init?: Parameters<typeof Sentry.init>[0]
+}
+
+/**
+ * Initialises `@sentry/node` for a Vyro service with secret-scrubbing already wired
+ * in. Idempotent and a no-op when no DSN is configured.
+ */
+export function initSentry(options: NodeSentryInitOptions): void {
+  if (initialised) return
+  const dsn = options.dsn ?? process.env.SENTRY_DSN
+  if (!dsn) {
+    initialised = true
+    return
+  }
+  Sentry.init({
+    ...createSentryScrubbers(options.scrub),
+    dsn,
+    serverName: options.serverName,
+    environment: options.environment ?? resolveEnvironment(),
+    tracesSampleRate: options.tracesSampleRate ?? DEFAULT_TRACES_SAMPLE_RATE,
+    ...options.init,
+  })
+  initialised = true
+}
+
+export interface CaptureContext {
+  tags?: Record<string, string>
+  extra?: Record<string, unknown>
+}
+
+/**
+ * Reports an exception with optional tags/extra. No-op until `initSentry` has run
+ * with a DSN. Consolidates the helper previously copied into individual services.
+ */
+export function captureException(
+  error: unknown,
+  context?: CaptureContext,
+): void {
+  if (!initialised) return
+  if (!context) {
+    Sentry.captureException(error)
+    return
+  }
+  Sentry.withScope((scope) => {
+    if (context.tags) {
+      for (const [key, value] of Object.entries(context.tags)) {
+        scope.setTag(key, value)
+      }
+    }
+    if (context.extra) scope.setExtras(context.extra)
+    Sentry.captureException(error)
+  })
+}

package/src/scrub.test.ts

@@ -0,0 +1,93 @@
+import { createSentryScrubbers, scrubSentrySensitiveData } from './index'
+
+describe('scrubSentrySensitiveData', () => {
+  it('redacts authorization and api-key style headers, case-insensitively', () => {
+    const headers: Record<string, unknown> = {
+      Authorization: 'Bearer abc123',
+      'x-api-key': 'secret-key',
+      'X-Api-Key': 'other',
+      apikey: 'k',
+      api_key: 'k2',
+      'x-hasura-admin-secret': 'hasura',
+      'content-type': 'application/json',
+    }
+    scrubSentrySensitiveData(headers)
+    expect(headers.Authorization).toBe('[Filtered]')
+    expect(headers['x-api-key']).toBe('[Filtered]')
+    expect(headers['X-Api-Key']).toBe('[Filtered]')
+    expect(headers.apikey).toBe('[Filtered]')
+    expect(headers.api_key).toBe('[Filtered]')
+    expect(headers['x-hasura-admin-secret']).toBe('[Filtered]')
+    expect(headers['content-type']).toBe('application/json')
+  })
+
+  it('walks nested objects and arrays', () => {
+    const value = {
+      list: [{ token: 't' }, { safe: 'ok' }],
+      nested: { deep: { secret: 's', keep: 1 } },
+    }
+    scrubSentrySensitiveData(value)
+    expect(value.list[0].token).toBe('[Filtered]')
+    expect((value.list[1] as { safe: string }).safe).toBe('ok')
+    expect(value.nested.deep.secret).toBe('[Filtered]')
+    expect(value.nested.deep.keep).toBe(1)
+  })
+
+  it('ignores primitives and null without throwing', () => {
+    expect(() => scrubSentrySensitiveData(null)).not.toThrow()
+    expect(() => scrubSentrySensitiveData('string')).not.toThrow()
+    expect(() => scrubSentrySensitiveData(42)).not.toThrow()
+  })
+
+  it('handles circular references', () => {
+    const a: Record<string, unknown> = { token: 't' }
+    a.self = a
+    expect(() => scrubSentrySensitiveData(a)).not.toThrow()
+    expect(a.token).toBe('[Filtered]')
+  })
+
+  it('supports custom placeholder and extra keys', () => {
+    const value = { requestId: 'abc', keep: 'y' }
+    scrubSentrySensitiveData(value, {
+      placeholder: '***',
+      extraKeys: ['requestid'],
+    })
+    expect(value.requestId).toBe('***')
+    expect(value.keep).toBe('y')
+  })
+})
+
+describe('createSentryScrubbers', () => {
+  it('scrubs request headers/cookies and returns the same event', () => {
+    const { beforeSend } = createSentryScrubbers()
+    const event = {
+      request: {
+        headers: { authorization: 'Bearer x', accept: '*/*' },
+        cookies: { session: 'abc', 'x-api-key': 'leak' },
+      },
+      extra: { apiKey: 'leak2', note: 'keep' },
+    }
+    const result = beforeSend(event)
+    expect(result).toBe(event)
+    expect(event.request.headers.authorization).toBe('[Filtered]')
+    expect(event.request.headers.accept).toBe('*/*')
+    expect(event.request.cookies['x-api-key']).toBe('[Filtered]')
+    expect(event.extra.apiKey).toBe('[Filtered]')
+    expect(event.extra.note).toBe('keep')
+  })
+
+  it('scrubs breadcrumb data and returns the same breadcrumb', () => {
+    const { beforeBreadcrumb } = createSentryScrubbers()
+    const breadcrumb = {
+      category: 'fetch',
+      data: {
+        request_headers: { 'x-api-key': 'leak' },
+        status_code: 200,
+      },
+    }
+    const result = beforeBreadcrumb(breadcrumb)
+    expect(result).toBe(breadcrumb)
+    expect(breadcrumb.data.request_headers['x-api-key']).toBe('[Filtered]')
+    expect(breadcrumb.data.status_code).toBe(200)
+  })
+})

package/src/scrub.ts

@@ -0,0 +1,85 @@
+/**
+ * SDK-agnostic Sentry scrubbing helpers.
+ *
+ * This package intentionally does NOT depend on any `@sentry/*` package so it can
+ * be dropped into services and frontends running different Sentry SDK versions
+ * (`@sentry/node`, `@sentry/react`, `@sentry/nextjs`, …). The public `beforeSend` /
+ * `beforeBreadcrumb` helpers use a generic identity signature (`<T>(x: T) => T`) so
+ * they satisfy every SDK's `beforeSend` / `beforeBreadcrumb` option type while
+ * operating on the event purely at runtime.
+ */
+
+/**
+ * Default set of key/header-name fragments that get redacted (case-insensitive).
+ * Matches `authorization`, `x-api-key` and every `api-key` / `apikey` / `api_key`
+ * variant, `x-hasura-admin-secret`, `access-token` / `refresh-token` / `token`,
+ * `secret`, `cookie`, `password` and `credential`.
+ */
+export const DEFAULT_SENSITIVE_KEY_PATTERN =
+  /authorization|api[-_ ]?key|x-hasura-admin-secret|access[-_ ]?token|refresh[-_ ]?token|token|secret|cookie|password|credential/i
+
+export interface SentryScrubOptions {
+  /** Extra regexes matched against key/header names (case-insensitive recommended). */
+  extraPatterns?: RegExp[]
+  /** Extra literal substrings matched against key/header names (case-insensitive). */
+  extraKeys?: string[]
+  /** Replace the whole default pattern instead of extending it. */
+  pattern?: RegExp
+  /** Value written in place of a redacted entry. Defaults to `"[Filtered]"`. */
+  placeholder?: string
+  /** Maximum object depth to walk. Defaults to `6`. */
+  maxDepth?: number
+}
+
+const buildMatcher = (
+  options: SentryScrubOptions,
+): ((key: string) => boolean) => {
+  const patterns: RegExp[] = [
+    options.pattern ?? DEFAULT_SENSITIVE_KEY_PATTERN,
+    ...(options.extraPatterns ?? []),
+  ]
+  const keys = (options.extraKeys ?? []).map((key) => key.toLowerCase())
+  return (key: string): boolean => {
+    if (patterns.some((pattern) => pattern.test(key))) return true
+    if (keys.length === 0) return false
+    const lower = key.toLowerCase()
+    return keys.some((needle) => lower.includes(needle))
+  }
+}
+
+/**
+ * Recursively redacts sensitive keys of `value` **in place**. Safe on any input:
+ * primitives and `null`/`undefined` are ignored, arrays are walked, and circular
+ * references are handled. Sensitive values are replaced with the placeholder.
+ */
+export const scrubSentrySensitiveData = (
+  value: unknown,
+  options: SentryScrubOptions = {},
+): void => {
+  const placeholder = options.placeholder ?? '[Filtered]'
+  const maxDepth = options.maxDepth ?? 6
+  const isSensitive = buildMatcher(options)
+  const seen = new WeakSet<object>()
+
+  const walk = (node: unknown, depth: number): void => {
+    if (!node || typeof node !== 'object' || depth > maxDepth) return
+    if (seen.has(node as object)) return
+    seen.add(node as object)
+
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, depth + 1)
+      return
+    }
+
+    const record = node as Record<string, unknown>
+    for (const key of Object.keys(record)) {
+      if (isSensitive(key)) {
+        record[key] = placeholder
+        continue
+      }
+      walk(record[key], depth + 1)
+    }
+  }
+
+  walk(value, 0)
+}

package/src/scrubbers.ts

@@ -0,0 +1,68 @@
+import { type SentryScrubOptions, scrubSentrySensitiveData } from './scrub'
+
+/**
+ * A pair of scrubbing hooks. The signatures are generic identity functions so the
+ * object can be spread straight into any SDK's `Sentry.init({ ... })` regardless of
+ * its `Event` / `Breadcrumb` types.
+ */
+export interface SentryScrubbers {
+  beforeSend: <T>(event: T) => T
+  beforeBreadcrumb: <T>(breadcrumb: T) => T
+}
+
+const scrubEvent = (event: unknown, options: SentryScrubOptions): void => {
+  if (!event || typeof event !== 'object') return
+  const record = event as Record<string, unknown>
+
+  const request = record.request as Record<string, unknown> | undefined
+  if (request) {
+    scrubSentrySensitiveData(request.headers, options)
+    scrubSentrySensitiveData(request.cookies, options)
+    scrubSentrySensitiveData(request.data, options)
+  }
+
+  scrubSentrySensitiveData(record.contexts, options)
+  scrubSentrySensitiveData(record.extra, options)
+  scrubSentrySensitiveData(record.tags, options)
+}
+
+const scrubBreadcrumb = (
+  breadcrumb: unknown,
+  options: SentryScrubOptions,
+): void => {
+  if (!breadcrumb || typeof breadcrumb !== 'object') return
+  scrubSentrySensitiveData(
+    (breadcrumb as Record<string, unknown>).data,
+    options,
+  )
+}
+
+/**
+ * Builds `beforeSend` / `beforeBreadcrumb` hooks that redact authorization headers,
+ * API keys, tokens and other secrets from outgoing Sentry events and breadcrumbs.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/node"
+ * import { createSentryScrubbers } from "@vyro-x/sentry"
+ *
+ * Sentry.init({
+ *   ...createSentryScrubbers(),
+ *   dsn: process.env.SENTRY_DSN,
+ * })
+ * ```
+ */
+export function createSentryScrubbers(
+  options: SentryScrubOptions = {},
+): SentryScrubbers {
+  return {
+    beforeSend: <T>(event: T): T => {
+      scrubEvent(event, options)
+      return event
+    },
+    beforeBreadcrumb: <T>(breadcrumb: T): T => {
+      scrubBreadcrumb(breadcrumb, options)
+      return breadcrumb
+    },
+  }
+}