@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/observability/block.tsx

@@ -0,0 +1,300 @@
+/**
+ * `createObservability(options)`: the observability block. Build it once at
+ * module scope (it starts the sinks, Sentry's `init` included), then:
+ *
+ *   <GenesisNativeApp blocks={[observability]}>   every error the shell catches → captureError
+ *   export default observability.wrap(RootLayout) Sentry's `wrap` (touch and profiler boundaries)
+ *   observability.track("auth.signed_in", { method: "email" })
+ *
+ * Its root (inside the shell) sets the user to the signed-in login's id and,
+ * with `useSegments` from expo-router, leaves a breadcrumb per route change
+ * and a `route.time_on_screen` timing for the route left. Route patterns
+ * (`/(app)/clients/[id]`) are used, never the values in them.
+ *
+ * Everything a sink receives has been scrubbed (see `scrub.ts`), and the
+ * last breadcrumbs and errors are kept, scrubbed, for the devtools overlay
+ * (`recent`).
+ */
+import { createContext, useContext, useEffect, useRef, useSyncExternalStore, type ComponentType, type ReactNode } from "react";
+import { defineBlock } from "@marktiderman/genesis-features/blocks";
+import { useSession } from "../auth";
+import type { NativeBlock, NativeBlockRootProps } from "../blocks";
+import type { ErrorReport } from "../errors";
+import { checkEvent, type EventProps, type EventSchema } from "./events";
+import { scrubString, scrubValue } from "./scrub";
+import { scrubBreadcrumb, scrubbedError, type Breadcrumb, type ErrorContext, type ObservabilitySink, type TimingTags } from "./sink";
+
+/** The FeatureId of the observability block. */
+export const OBSERVABILITY_BLOCK_ID = "observability";
+
+/** A caught error as the devtools overlay shows it (scrubbed). */
+export interface RecentError {
+  at: number;
+  name: string;
+  message: string;
+  source: string;
+  fatal: boolean;
+}
+
+export interface RecentActivity {
+  /** Oldest first. Navigation, events and the app's breadcrumbs. */
+  breadcrumbs: readonly Breadcrumb[];
+  /** Oldest first. */
+  errors: readonly RecentError[];
+}
+
+export interface RecentStore {
+  getState(): RecentActivity;
+  subscribe(listener: () => void): () => void;
+  clear(): void;
+}
+
+export interface ObservabilityOptions<E extends EventSchema = EventSchema> {
+  /** Where everything goes: `sentrySink(Sentry, …)`, `consoleSink()` in development, `observeSink(Observe)`. */
+  sinks: readonly (ObservabilitySink | null | undefined | false)[];
+  /** The app's analytics events (`defineEvents`). Without it, `track` accepts nothing. */
+  events?: E;
+  /** `useSegments` from expo-router: route breadcrumbs and `route.time_on_screen` timings. */
+  useSegments?: () => readonly string[];
+  /** How many breadcrumbs and errors `recent` keeps. Default 50 and 20. */
+  recent?: { breadcrumbs?: number; errors?: number };
+  /** A sink threw, or `track` was called with something the schema doesn't allow. Default `console.warn` in development. */
+  onProblem?: (problem: string, error?: unknown) => void;
+  now?: () => number;
+}
+
+export interface ObservabilityBlock<E extends EventSchema = EventSchema> extends NativeBlock<typeof OBSERVABILITY_BLOCK_ID> {
+  readonly sinks: readonly ObservabilitySink[];
+  readonly events: E | undefined;
+  /** Report an error. The shell calls it for every error it catches. */
+  captureError(error: unknown, context?: Partial<ErrorContext>): void;
+  breadcrumb(crumb: Breadcrumb): void;
+  /** The login's id only. The block's root sets it from the session. */
+  setUser(id: string | null): void;
+  /** An analytics event from the schema. Anything else is dropped and reported. */
+  track<N extends keyof E & string>(name: N, props?: EventProps<E[N]>): void;
+  timing(name: string, ms: number, tags?: TimingTags): void;
+  /** The root layout wrapped by each sink that wraps (Sentry's `wrap`). Use once: `export default observability.wrap(RootLayout)`. */
+  wrap<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+  /** The last breadcrumbs and errors, scrubbed, for the devtools overlay. */
+  readonly recent: RecentStore;
+  /** For the shell: every error it catches. */
+  readonly onError: (error: Error, report: ErrorReport) => void;
+  readonly Root: ComponentType<NativeBlockRootProps>;
+}
+
+declare const __DEV__: boolean | undefined;
+
+const TIMING_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+
+function createRecentStore(maxCrumbs: number, maxErrors: number): RecentStore & { addCrumb(c: Breadcrumb): void; addError(e: RecentError): void } {
+  let state: RecentActivity = { breadcrumbs: [], errors: [] };
+  const listeners = new Set<() => void>();
+  const emit = () => listeners.forEach((l) => l());
+  const push = <T,>(list: readonly T[], item: T, max: number) => (list.length >= max ? [...list.slice(list.length - max + 1), item] : [...list, item]);
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    clear() {
+      state = { breadcrumbs: [], errors: [] };
+      emit();
+    },
+    addCrumb(crumb) {
+      state = { ...state, breadcrumbs: push(state.breadcrumbs, crumb, maxCrumbs) };
+      emit();
+    },
+    addError(error) {
+      state = { ...state, errors: push(state.errors, error, maxErrors) };
+      emit();
+    },
+  };
+}
+
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(typeof value === "string" ? value : "Unknown error");
+}
+
+/** Build the block once, at module scope, before the root layout renders. @stability Beta */
+export function createObservability<const E extends EventSchema = EventSchema>(options: ObservabilityOptions<E>): ObservabilityBlock<E> {
+  const sinks = options.sinks.filter((s): s is ObservabilitySink => Boolean(s));
+  const now = options.now ?? Date.now;
+  const problem =
+    options.onProblem ??
+    ((message: string, error?: unknown) => {
+      if (typeof __DEV__ !== "undefined" && __DEV__) console.warn(`[observability] ${message}`, error ?? "");
+    });
+  const recent = createRecentStore(options.recent?.breadcrumbs ?? 50, options.recent?.errors ?? 20);
+  let route: string | null = null;
+  let user: string | null | undefined;
+
+  // One sink failing never stops the others, and never throws into the caller (an error handler, a render).
+  const each = (method: string, call: (sink: ObservabilitySink) => void) => {
+    for (const sink of sinks) {
+      try {
+        call(sink);
+      } catch (error) {
+        try {
+          problem(`${sink.name}.${method} threw`, error);
+        } catch {
+          // ignore a failing reporter
+        }
+      }
+    }
+  };
+
+  // Never throws into the caller (an effect, a handler): a record that can't be scrubbed is dropped.
+  const breadcrumb = (input: Breadcrumb) => {
+    let crumb: Breadcrumb;
+    try {
+      crumb = scrubBreadcrumb({ ...input, timestamp: input.timestamp ?? now() });
+    } catch (error) {
+      problem("breadcrumb dropped: it could not be scrubbed", error);
+      return;
+    }
+    recent.addCrumb(crumb);
+    each("breadcrumb", (s) => s.breadcrumb?.(crumb));
+  };
+
+  const captureError = (value: unknown, context: Partial<ErrorContext> = {}) => {
+    const error = toError(value);
+    const full: ErrorContext = { fatal: context.fatal ?? false, source: context.source ?? "app", route: context.route ?? route, componentStack: context.componentStack };
+    let safe: Error | undefined;
+    const scrubbed = () => (safe ??= scrubbedError(error));
+    try {
+      recent.addError({ at: now(), name: error.name, message: scrubString(error.message), source: full.source, fatal: full.fatal });
+    } catch {
+      // never let the overlay's list stop a report
+    }
+    const forSinks = full.componentStack ? { ...full, componentStack: scrubString(full.componentStack) } : full;
+    each("captureError", (s) => s.captureError?.(s.scrubsErrors ? error : scrubbed(), s.scrubsErrors ? full : forSinks));
+  };
+
+  const setUser = (id: string | null) => {
+    if (id === user) return;
+    user = id;
+    each("setUser", (s) => s.setUser?.(id));
+  };
+
+  const track = (name: string, props?: Readonly<Record<string, unknown>>) => {
+    const check = options.events ? checkEvent(options.events, name, props) : ({ ok: false, problem: "no event schema: pass `events: defineEvents({…})`" } as const);
+    if (!check.ok) {
+      problem(`track dropped: ${check.problem}`);
+      return;
+    }
+    recent.addCrumb({ category: "event", message: name, level: "info", data: check.props, timestamp: now() });
+    each("event", (s) => s.event?.(name, check.props));
+  };
+
+  const timing = (name: string, ms: number, tags?: TimingTags) => {
+    if (!Number.isFinite(ms) || ms < 0) return;
+    // A name like an event's (`route.time_on_screen`), never text with values in it.
+    if (!TIMING_NAME.test(name)) {
+      problem(`timing dropped: "${scrubString(name)}" is not lower-case words joined by "."`);
+      return;
+    }
+    let safeTags: TimingTags | undefined;
+    try {
+      safeTags = tags ? (scrubValue(tags) as TimingTags) : undefined;
+    } catch (error) {
+      problem("timing dropped: its tags could not be scrubbed", error);
+      return;
+    }
+    each("timing", (s) => s.timing?.(name, ms, safeTags));
+  };
+
+  const declaration = defineBlock<typeof OBSERVABILITY_BLOCK_ID, ComponentType<never>>({
+    id: OBSERVABILITY_BLOCK_ID,
+    platforms: ["native"],
+    contributes: {
+      privacy: {
+        collects: [
+          // genesis-cli's PRIVACY_BLOCKS.observability mirrors this (with events) for the iOS
+          // privacy manifest; observability/block.test.tsx keeps the two the same.
+          { type: "crash data", purposes: ["app functionality"], linked: true, tracking: false },
+          { type: "performance data", purposes: ["app functionality"], linked: true, tracking: false },
+          // Sentry's device and OS details, breadcrumbs and sessions.
+          { type: "other diagnostic data", purposes: ["app functionality"], linked: true, tracking: false },
+          { type: "user id", purposes: options.events ? ["app functionality", "analytics"] : ["app functionality"], linked: true, tracking: false },
+          ...(options.events ? [{ type: "product interaction", purposes: ["analytics"], linked: true, tracking: false }] : []),
+        ],
+        notes: [
+          "Crash reports, timings and analytics events carry the login's id only; emails, tokens, keys and query strings are removed on the device before anything is sent.",
+        ],
+      },
+    },
+  });
+
+  const useSegments = options.useSegments;
+  function RouteTracker() {
+    const segments = (useSegments as () => readonly string[])();
+    const path = `/${segments.join("/")}`;
+    const last = useRef<{ path: string; at: number } | null>(null);
+    useEffect(() => {
+      const at = now();
+      const previous = last.current;
+      if (previous?.path === path) return;
+      route = path;
+      breadcrumb({ category: "navigation", message: path, data: previous ? { from: previous.path } : undefined, timestamp: at });
+      if (previous) timing("route.time_on_screen", at - previous.at, { route: previous.path });
+      last.current = { path, at };
+    }, [path]);
+    return null;
+  }
+
+  function UserTracker() {
+    const { userId } = useSession();
+    useEffect(() => setUser(userId ?? null), [userId]);
+    return null;
+  }
+
+  const block: ObservabilityBlock<E> = {
+    ...declaration,
+    sinks,
+    events: options.events,
+    captureError,
+    breadcrumb,
+    setUser,
+    track: track as ObservabilityBlock<E>["track"],
+    timing,
+    recent,
+    wrap(root) {
+      return sinks.reduce((wrapped, sink) => (sink.wrap ? sink.wrap(wrapped) : wrapped), root);
+    },
+    onError: (error, report) => captureError(error, { fatal: report.fatal, source: report.source, componentStack: report.componentStack }),
+    Root: function ObservabilityRoot({ children }: NativeBlockRootProps) {
+      return (
+        <ObservabilityContext.Provider value={block as ObservabilityBlock}>
+          <UserTracker />
+          {useSegments ? <RouteTracker /> : null}
+          {children}
+        </ObservabilityContext.Provider>
+      );
+    },
+  };
+  return block;
+}
+
+const ObservabilityContext = createContext<ObservabilityBlock | null>(null);
+
+/** Provides a block to the hooks without its root (rung 4). @stability Beta */
+export function ObservabilityProvider({ block, children }: { block: ObservabilityBlock; children?: ReactNode }) {
+  return <ObservabilityContext.Provider value={block}>{children}</ObservabilityContext.Provider>;
+}
+
+/** The block, or `null` when it is off (so a screen can call it whether or not the block is on). @stability Beta */
+export function useObservability(): ObservabilityBlock | null {
+  return useContext(ObservabilityContext);
+}
+
+/** The last breadcrumbs and errors, scrubbed; empty when the block is off. @stability Beta */
+export function useRecentActivity(block?: ObservabilityBlock | null): RecentActivity {
+  const fromContext = useObservability();
+  const store = (block ?? fromContext)?.recent ?? EMPTY_STORE;
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}
+
+const EMPTY: RecentActivity = { breadcrumbs: [], errors: [] };
+const EMPTY_STORE: RecentStore = { getState: () => EMPTY, subscribe: () => () => {}, clear: () => {} };

package/src/observability/events.ts

@@ -0,0 +1,89 @@
+/**
+ * Typed analytics events: the app lists every event and the props each may
+ * carry once, and `track(name, props)` accepts nothing else. A prop is a
+ * closed list of strings, a number or a boolean, never free text, so an
+ * event can't carry a name, an email or a message someone typed.
+ *
+ * ```ts
+ * export const events = defineEvents({
+ *   "auth.signed_in": { method: ["email", "apple"] },
+ *   "settings.opened": {},
+ *   "checkin.saved": { mood: "number", first: "boolean" },
+ * });
+ * ```
+ *
+ * At run time an unknown event, an unknown prop or a value outside its list
+ * is dropped and reported (a `console.warn` in development, `onInvalid`
+ * always), so a bad call is loud and still sends nothing.
+ */
+
+/** A closed list of strings, `"number"` (finite) or `"boolean"`. */
+export type EventPropSpec = readonly string[] | "number" | "boolean";
+
+/** Every event, by name, with the props it may carry. */
+export type EventSchema = Readonly<Record<string, Readonly<Record<string, EventPropSpec>>>>;
+
+type PropValue<S> = S extends readonly (infer L)[] ? L : S extends "number" ? number : S extends "boolean" ? boolean : never;
+
+/** The props of one event: every prop optional, each its spec's type. */
+export type EventProps<S extends Readonly<Record<string, EventPropSpec>>> = { readonly [K in keyof S]?: PropValue<S[K]> };
+
+/** What a sink receives: the checked props. */
+export type EventValues = Readonly<Record<string, string | number | boolean>>;
+
+// Lower-case words joined by `.` or `_`: `auth.signed_in`, `checkin.saved`.
+const EVENT_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+const PROP_NAME = /^[a-z][a-z0-9_]*$/;
+const MAX_PROPS = 25;
+const MAX_LITERAL = 64;
+
+/**
+ * Declare the app's events. Checks names (lower-case, dot-separated), prop
+ * names, and that each list has at least one short value, and throws listing
+ * every problem, so a bad schema fails where it is written.
+ *
+ * @stability Beta
+ */
+export function defineEvents<const E extends EventSchema>(schema: E): E {
+  const problems: string[] = [];
+  for (const [name, props] of Object.entries(schema)) {
+    if (!EVENT_NAME.test(name)) problems.push(`"${name}": an event name is lower-case words joined by "." (auth.signed_in)`);
+    const keys = Object.keys(props);
+    if (keys.length > MAX_PROPS) problems.push(`"${name}": at most ${MAX_PROPS} props`);
+    for (const key of keys) {
+      const spec = props[key];
+      if (!PROP_NAME.test(key)) problems.push(`"${name}".${key}: a prop name is lower-case letters, digits and "_"`);
+      if (Array.isArray(spec)) {
+        if (spec.length === 0) problems.push(`"${name}".${key}: an empty list allows nothing`);
+        for (const v of spec) if (typeof v !== "string" || v.length === 0 || v.length > MAX_LITERAL) problems.push(`"${name}".${key}: "${String(v)}" must be 1-${MAX_LITERAL} characters`);
+      } else if (spec !== "number" && spec !== "boolean") {
+        problems.push(`"${name}".${key}: a prop is a list of strings, "number" or "boolean" (free text is not allowed)`);
+      }
+    }
+  }
+  if (problems.length) throw new Error(`Invalid events:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+  return Object.freeze(schema);
+}
+
+export type EventCheck = { ok: true; props: EventValues } | { ok: false; problem: string };
+
+/** Check one call against the schema: the props to send, or why nothing is sent. */
+export function checkEvent(schema: EventSchema, name: string, props: Readonly<Record<string, unknown>> | undefined): EventCheck {
+  if (!Object.prototype.hasOwnProperty.call(schema, name)) return { ok: false, problem: `"${name}" is not in the event schema` };
+  const specs = schema[name] ?? {};
+  const out: Record<string, string | number | boolean> = {};
+  for (const [key, value] of Object.entries(props ?? {})) {
+    if (value === undefined) continue;
+    if (!Object.prototype.hasOwnProperty.call(specs, key)) return { ok: false, problem: `"${name}" has no prop "${key}"` };
+    const spec = specs[key];
+    const fits =
+      spec === "number"
+        ? typeof value === "number" && Number.isFinite(value)
+        : spec === "boolean"
+          ? typeof value === "boolean"
+          : typeof value === "string" && (spec as readonly string[]).includes(value);
+    if (!fits) return { ok: false, problem: `"${name}".${key}: ${JSON.stringify(value)} is not allowed` };
+    out[key] = value as string | number | boolean;
+  }
+  return { ok: true, props: out };
+}

package/src/observability/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@marktiderman/genesis-native/observability`: crash and error reporting,
+ * breadcrumbs, the user id, typed analytics events and timings, through
+ * vendor-neutral sinks, with PII scrubbed on the device first.
+ *
+ * Rung 1: `<GenesisNativeApp blocks={[createObservability({ sinks })]}>`.
+ * Rung 3: the sinks (`sentrySink`, `observeSink`, `consoleSink`), the
+ * scrubber (`scrubEvent`, `scrubString`, …) and `defineEvents`.
+ * Rung 4: `useObservability`, `useRecentActivity`.
+ *
+ * Optional peers, passed in rather than imported: `@sentry/react-native`
+ * (`sentrySink`) and `expo-observe` (`observeSink`).
+ *
+ * @stability Beta
+ */
+export {
+  createObservability,
+  OBSERVABILITY_BLOCK_ID,
+  ObservabilityProvider,
+  useObservability,
+  useRecentActivity,
+  type ObservabilityBlock,
+  type ObservabilityOptions,
+  type RecentActivity,
+  type RecentError,
+  type RecentStore,
+} from "./block";
+export {
+  consoleSink,
+  observeSink,
+  scrubbedError,
+  scrubBreadcrumb,
+  type Breadcrumb,
+  type BreadcrumbLevel,
+  type ConsoleSinkOptions,
+  type ErrorContext,
+  type ObservabilitySink,
+  type ObserveLike,
+  type ObserveSinkOptions,
+  type TimingTags,
+} from "./sink";
+export { sentrySink, sentryRelease, signatureTags, type SentryLike, type SentrySinkOptions } from "./sentry";
+export { defineEvents, checkEvent, type EventCheck, type EventPropSpec, type EventProps, type EventSchema, type EventValues } from "./events";
+export { FILTERED, isSecretKey, scrubEvent, scrubRecord, scrubString, scrubUrl, scrubValue, type ScrubbableEvent } from "./scrub";

package/src/observability/scrub.ts

@@ -0,0 +1,166 @@
+/**
+ * The PII scrubber every sink's input goes through by default: text is
+ * rewritten by pattern (an email, a phone number, a JWT, a Supabase key, a
+ * bearer token, a token in a query string, row values in a database error),
+ * values under a key that names a secret or a contact detail are replaced
+ * whole, and URLs lose their query and fragment (PostgREST filters carry
+ * record ids, auth callbacks carry codes). Strings are cut at 4 KB first, so
+ * a huge log line can't stall the JS thread.
+ *
+ * What it can't know: a person's name in free text. Keep names out of error
+ * messages and breadcrumbs; touch breadcrumbs lose their labels in
+ * `sentrySink` for this reason.
+ *
+ * Pattern-based on values, not an allowlist of keys: a key allowlist misses
+ * `refresh failed: eyJhbGciOi…`, which is the shape that actually occurs.
+ *
+ * Fail closed: `scrubEvent` and `scrubRecord` return `null` (drop it) when
+ * scrubbing itself throws, never the unscrubbed input.
+ */
+
+/** What replaces a value under a secret-looking key. */
+export const FILTERED = "[Filtered]";
+
+// Keys whose value is a secret (or a contact detail) whatever it looks like.
+// Matched case-insensitively with `-`, `_`, `.` and spaces removed: exactly
+// for the short, ambiguous ones, as a part of the key for the rest
+// (`x-supabase-api-key`, `user.email`, `refresh_token_hash`).
+const SECRET_KEY_EXACT = /^(session|sessionid|dsn|otp|code|verifier|codeverifier|privatekey|refresh|pwd|key)$/;
+const SECRET_KEY_PART = /(authoriz|cookie|passw|secret|token|apikey|credential|jwt|email|phone|servicerole)/;
+
+/** True when a value under `key` is a secret (or contact detail) whatever it looks like. */
+export function isSecretKey(key: string): boolean {
+  const k = key.replace(/[-_.\s]/g, "").toLowerCase();
+  return SECRET_KEY_EXACT.test(k) || SECRET_KEY_PART.test(k);
+}
+
+// Sentry's own ids and envelope fields: 32-hex values the hex rule would break, never PII.
+const ID_KEY = /^(event_id|trace_id|span_id|parent_span_id|profile_id|replay_id|debug_id|code_id|public_key|segment_id|sampled|release|dist|environment)$/;
+
+// Fields dropped whole: query strings travel as their own fields too (Sentry's http breadcrumbs,
+// spans and requests), and bodies and PostgREST `details` carry row values.
+const DROPPED_KEY = /^(query_string|http\.query|http\.fragment|url\.query|url\.fragment|request_body|response_body|body|cookies|details)$/i;
+
+/** Longest string scrubbed in full; the rest is cut off (the patterns stay fast on huge logs). */
+export const MAX_STRING = 4096;
+
+const PATTERNS: readonly [RegExp, string][] = [
+  // The query string and fragment of a URL with a scheme anywhere in text (a span's
+  // "GET https://…?id=eq.42", a deep link "myapp://reset?token_hash=…").
+  [/\b([a-z][a-z0-9+.-]{0,31}:\/\/[^\s?#"'<>]{0,2048})[?#][^\s"'<>]*/gi, "$1"],
+  // …and of a path ("POST /rest/v1/rpc/find?email=eq.…").
+  [/(^|[\s"'(=])(\/[^\s?#"'<>]{0,2048})\?[^\s"'<>]*/g, "$1$2"],
+  // JWTs: Supabase access tokens and the legacy anon / service_role keys.
+  [/\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*/g, "[jwt]"],
+  // Supabase's API keys (sb_secret_…, sb_publishable_…).
+  [/\bsb_(?:secret|publishable)_[A-Za-z0-9_-]{8,}/g, "[supabase-key]"],
+  // `Authorization: Bearer …` copied into a message.
+  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 [token]"],
+  // Tokens in a query string or a fragment left without a scheme.
+  [
+    /([?&#](?:access_token|refresh_token|id_token|provider_token|provider_refresh_token|token|token_hash|code|apikey|api_key|key|password|secret|email|phone)=)[^&#\s"']+/gi,
+    "$1[Filtered]",
+  ],
+  // Row values in PostgreSQL errors: `Failing row contains (…)`, `Key (email)=(…)`.
+  [/(Failing row contains )\([^)]*\)/g, "$1(…)"],
+  [/(Key \([^)]{0,256}\)=)\([^)]*\)/g, "$1(…)"],
+  // Email addresses, also percent-encoded (`a%40b.co`). Bounded, so a long run of letters can't backtrack.
+  [/[A-Za-z0-9._%+-]{1,64}(?:@|%40)(?:[A-Za-z0-9-]{1,63}\.){1,8}[A-Za-z]{2,24}/g, "[email]"],
+  // Phone numbers: international (`+1 555 555 0101`) and North American (`555-555-0101`).
+  [/\+\d[\d\s().-]{6,18}\d/g, "[phone]"],
+  [/\b\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g, "[phone]"],
+  // Long opaque hex runs: API keys, refresh tokens, DSN secrets. Linear: a run starts only after a non-hex character.
+  [/(^|[^A-Fa-f0-9])[A-Fa-f0-9]{32,}(?![A-Fa-f0-9])/g, "$1[hex]"],
+];
+
+/** A string with every URL query, email, phone number, JWT, Supabase key, bearer token and query-string token replaced. */
+export function scrubString(value: string): string {
+  let out = value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…[truncated]` : value;
+  for (const [pattern, replacement] of PATTERNS) out = out.replace(pattern, replacement);
+  return out;
+}
+
+/** A URL without its query string and fragment, then scrubbed (an email in a path). */
+export function scrubUrl(value: string): string {
+  const cut = value.search(/[?#]/);
+  return scrubString(cut === -1 ? value : value.slice(0, cut));
+}
+
+// Keys whose string value is cut at `?` when it is a URL.
+const URL_KEY = /^(url|href|from|to|uri|description|http\.url|url\.full)$/i;
+const MAX_DEPTH = 8;
+
+/**
+ * A deep copy of `value` with every string scrubbed and every value under a
+ * secret key replaced. Cycles become `"[Circular]"`; past 8 levels,
+ * `"[Truncated]"`. Errors become `{ name, message }`. Header lists
+ * (`[["authorization", "…"]]`) are treated like objects.
+ */
+export function scrubValue(value: unknown, key = "", depth = 0, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (key && isSecretKey(key)) return value === undefined || value === null || value === "" ? value : FILTERED;
+  if (typeof value === "string") {
+    if (key && ID_KEY.test(key)) return value;
+    return URL_KEY.test(key) ? scrubUrl(value) : scrubString(value);
+  }
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[Circular]";
+  if (depth >= MAX_DEPTH) return "[Truncated]";
+  seen.add(value);
+  if (value instanceof Error) return { name: value.name, message: scrubString(value.message) };
+  if (Array.isArray(value)) {
+    // A `[name, value]` pair (fetch's header lists): the name decides, as for an object key.
+    if (value.length === 2 && typeof value[0] === "string" && isSecretKey(value[0])) return [value[0], FILTERED];
+    return value.map((item) => scrubValue(item, "", depth + 1, seen));
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (DROPPED_KEY.test(k)) continue;
+    out[k] = scrubValue(v, k, depth + 1, seen);
+  }
+  return out;
+}
+
+/** The fields of a Sentry-shaped event `scrubEvent` treats specially. Anything else is scrubbed by value. */
+export interface ScrubbableEvent {
+  user?: { id?: unknown; [key: string]: unknown } | null;
+  request?: { url?: unknown; method?: unknown; headers?: unknown; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+/**
+ * The event with the user reduced to its id, the request reduced to its
+ * method, URL (cut at `?`) and scrubbed headers, and every other value
+ * scrubbed. `null` when scrubbing threw: fail closed, send nothing rather
+ * than PII.
+ */
+export function scrubEvent<E extends ScrubbableEvent>(event: E): E | null {
+  try {
+    // Sentry's processing metadata (scopes, the sampling context its envelope header is built
+    // from) is never sent as part of the event: pass it through, or the envelope breaks.
+    const { user, request, sdkProcessingMetadata, ...rest } = event;
+    const out = scrubValue(rest) as E;
+    if (sdkProcessingMetadata !== undefined) (out as ScrubbableEvent).sdkProcessingMetadata = sdkProcessingMetadata;
+    if (user !== undefined) {
+      (out as ScrubbableEvent).user = user && user.id !== undefined && user.id !== null ? { id: scrubString(String(user.id)) } : null;
+    }
+    if (request && typeof request === "object") {
+      const safe: Record<string, unknown> = {};
+      if (typeof request.url === "string") safe.url = scrubUrl(request.url);
+      if (typeof request.method === "string") safe.method = request.method;
+      if (request.headers && typeof request.headers === "object") safe.headers = scrubValue(request.headers);
+      (out as ScrubbableEvent).request = safe;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/** A breadcrumb, span or any record, scrubbed by value. `null` when scrubbing threw (fail closed). */
+export function scrubRecord<R extends object>(record: R): R | null {
+  try {
+    return scrubValue(record) as R;
+  } catch {
+    return null;
+  }
+}