@heystack/otel 0.18.0 → 0.19.0

package/dist/redact.d.ts

@@ -0,0 +1,57 @@
+/** Replacement written in place of a redacted query/fragment parameter value. */
+export declare const REDACTED = "REDACTED";
+/**
+ * Query/fragment parameter names whose VALUES are replaced with `REDACTED`
+ * before a URL is recorded. Compared case-insensitively against the decoded key.
+ * `state` is intentionally NOT listed (OAuth `state` is an anti-CSRF nonce, not a
+ * credential, and it is useful when debugging a broken login redirect).
+ */
+export declare const DEFAULT_REDACTED_QUERY_PARAMS: readonly string[];
+/** Options controlling how URLs are redacted before they are recorded. */
+export interface UrlRedactionOptions {
+    /**
+     * Extra query/fragment parameter names to redact, ADDED to
+     * {@link DEFAULT_REDACTED_QUERY_PARAMS} (case-insensitive). Pass `false` to
+     * turn query/fragment parameter redaction off entirely. Credentials embedded
+     * as URL userinfo (`https://user:pass@host`) are always stripped.
+     */
+    redactQueryParams?: readonly string[] | false;
+}
+/** Privacy options shared by the server entries (`/node`, `/next`, `/workers`). */
+export interface SpanPrivacyOptions extends UrlRedactionOptions {
+    /**
+     * Record the end-user's IP address (`client.address`, plus `http.client_ip` /
+     * peer-address attributes on SERVER spans under `/node`). **Off by default** —
+     * an IP address is personal data in most jurisdictions. Set `true` only if you
+     * have a lawful basis and have told your users.
+     */
+    captureClientIp?: boolean;
+}
+export type UrlRedactor = (url: string) => string;
+/** Build a reusable redactor (pre-computes the key set). */
+export declare function makeUrlRedactor(opts?: UrlRedactionOptions): UrlRedactor;
+/**
+ * Redact secrets from a URL before it is recorded: strips userinfo
+ * (`https://user:pass@host` → `https://host`) and replaces the VALUE of every
+ * sensitive query or fragment parameter (see
+ * {@link DEFAULT_REDACTED_QUERY_PARAMS}) with `REDACTED`. Everything else —
+ * scheme, host, path, non-sensitive parameters, plain `#anchors` — is kept
+ * byte-for-byte. Works on absolute and relative URLs (`/cb?code=…`).
+ */
+export declare function redactUrl(url: string, opts?: UrlRedactionOptions): string;
+/** Span/log attributes that hold a full or relative URL. */
+export declare const URL_ATTRS: readonly ["url.full", "http.url", "http.target", "url.original"];
+/** End-user IP attributes, dropped on every span unless `captureClientIp`. */
+export declare const CLIENT_IP_ATTRS: readonly ["client.address", "http.client_ip"];
+/** Peer-address attributes that equal the end-user (or edge proxy) IP on a SERVER span. */
+export declare const SERVER_PEER_IP_ATTRS: readonly ["net.peer.ip", "network.peer.address", "net.sock.peer.addr"];
+/**
+ * Return `attrs` with every URL-bearing attribute redacted and, unless
+ * `captureClientIp`, end-user IP attributes removed. Returns the SAME object
+ * when nothing changed (cheap common path), otherwise a shallow copy.
+ */
+export declare function applySpanPrivacy(attrs: Record<string, unknown>, o: {
+    redact: UrlRedactor;
+    captureClientIp?: boolean;
+    isServer?: boolean;
+}): Record<string, unknown>;

package/dist/redact.js

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// URL + client-IP privacy helpers (shared by /node, /workers and /web)
+//
+// Pure string logic with NO imports — safe in every entry, including the
+// WinterCG-only `/workers` build and the browser `/web` bundle. Deliberately
+// avoids `new URL(...).href` re-serialisation so a redacted URL keeps the exact
+// spelling of everything that was not redacted (and so relative targets such as
+// `http.target` = `/cb?code=…` work without a base).
+// ---------------------------------------------------------------------------
+/** Replacement written in place of a redacted query/fragment parameter value. */
+export const REDACTED = "REDACTED";
+/**
+ * Query/fragment parameter names whose VALUES are replaced with `REDACTED`
+ * before a URL is recorded. Compared case-insensitively against the decoded key.
+ * `state` is intentionally NOT listed (OAuth `state` is an anti-CSRF nonce, not a
+ * credential, and it is useful when debugging a broken login redirect).
+ */
+export const DEFAULT_REDACTED_QUERY_PARAMS = [
+    "key",
+    "api_key",
+    "apikey",
+    "api-key",
+    "token",
+    "access_token",
+    "refresh_token",
+    "id_token",
+    "auth_token",
+    "api_token",
+    "oauth_token",
+    "oauth_signature",
+    "code",
+    "sig",
+    "signature",
+    "password",
+    "passwd",
+    "pass",
+    "secret",
+    "client_secret",
+    "auth",
+    "authorization",
+    "session",
+    "sessionid",
+    "session_id",
+    "jwt",
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "x-goog-signature",
+    "x-goog-credential",
+];
+function safeDecode(s) {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, " "));
+    }
+    catch {
+        return s;
+    }
+}
+/** Redact sensitive parameter values in a bare `a=1&b=2` string. */
+function redactParams(qs, keys) {
+    if (!qs || keys.size === 0)
+        return qs;
+    let changed = false;
+    const parts = qs.split("&").map((part) => {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            return part; // bare flag, no value to leak
+        const key = part.slice(0, eq);
+        if (!keys.has(safeDecode(key).trim().toLowerCase()))
+            return part;
+        if (part.slice(eq + 1) === REDACTED)
+            return part;
+        changed = true;
+        return `${key}=${REDACTED}`;
+    });
+    return changed ? parts.join("&") : qs;
+}
+/** Strip `user[:password]@` from an absolute (or protocol-relative) URL. */
+const USERINFO_RE = /^((?:[a-zA-Z][a-zA-Z0-9+.-]*:)?\/\/)[^/?#]*@/;
+function redactWith(url, keys) {
+    let out = url.replace(USERINFO_RE, "$1");
+    const hash = out.indexOf("#");
+    let fragment;
+    if (hash >= 0) {
+        fragment = out.slice(hash + 1);
+        out = out.slice(0, hash);
+    }
+    const q = out.indexOf("?");
+    if (q >= 0)
+        out = `${out.slice(0, q)}?${redactParams(out.slice(q + 1), keys)}`;
+    if (fragment !== undefined) {
+        // OAuth implicit flow puts tokens in the fragment (`#access_token=…`); hash
+        // routers put a query after a route (`#/cb?code=…`). Plain anchors pass.
+        const fq = fragment.indexOf("?");
+        if (fq >= 0) {
+            fragment = `${fragment.slice(0, fq)}?${redactParams(fragment.slice(fq + 1), keys)}`;
+        }
+        else if (fragment.includes("=")) {
+            fragment = redactParams(fragment, keys);
+        }
+        out = `${out}#${fragment}`;
+    }
+    return out;
+}
+function keySet(opts) {
+    if (opts?.redactQueryParams === false)
+        return new Set();
+    const extra = Array.isArray(opts?.redactQueryParams) ? opts.redactQueryParams : [];
+    return new Set([...DEFAULT_REDACTED_QUERY_PARAMS, ...extra].map((k) => String(k).trim().toLowerCase()));
+}
+/** Build a reusable redactor (pre-computes the key set). */
+export function makeUrlRedactor(opts) {
+    const keys = keySet(opts);
+    return (url) => (typeof url === "string" && url ? redactWith(url, keys) : url);
+}
+const defaultRedactor = makeUrlRedactor();
+/**
+ * Redact secrets from a URL before it is recorded: strips userinfo
+ * (`https://user:pass@host` → `https://host`) and replaces the VALUE of every
+ * sensitive query or fragment parameter (see
+ * {@link DEFAULT_REDACTED_QUERY_PARAMS}) with `REDACTED`. Everything else —
+ * scheme, host, path, non-sensitive parameters, plain `#anchors` — is kept
+ * byte-for-byte. Works on absolute and relative URLs (`/cb?code=…`).
+ */
+export function redactUrl(url, opts) {
+    return opts ? makeUrlRedactor(opts)(url) : defaultRedactor(url);
+}
+/** Span/log attributes that hold a full or relative URL. */
+export const URL_ATTRS = ["url.full", "http.url", "http.target", "url.original"];
+/** Attributes that hold a bare query string (no leading `?`). */
+const QUERY_ATTRS = ["url.query"];
+/** Attributes that hold a bare fragment (no leading `#`). */
+const FRAGMENT_ATTRS = ["url.fragment"];
+/** End-user IP attributes, dropped on every span unless `captureClientIp`. */
+export const CLIENT_IP_ATTRS = ["client.address", "http.client_ip"];
+/** Peer-address attributes that equal the end-user (or edge proxy) IP on a SERVER span. */
+export const SERVER_PEER_IP_ATTRS = [
+    "net.peer.ip",
+    "network.peer.address",
+    "net.sock.peer.addr",
+];
+/**
+ * Return `attrs` with every URL-bearing attribute redacted and, unless
+ * `captureClientIp`, end-user IP attributes removed. Returns the SAME object
+ * when nothing changed (cheap common path), otherwise a shallow copy.
+ */
+export function applySpanPrivacy(attrs, o) {
+    let out;
+    const set = (k, v) => {
+        out ??= { ...attrs };
+        if (v === undefined)
+            delete out[k];
+        else
+            out[k] = v;
+    };
+    for (const k of URL_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string") {
+            const r = o.redact(v);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    for (const k of QUERY_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string" && v) {
+            const r = o.redact(`?${v.replace(/^\?/, "")}`).slice(1);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    for (const k of FRAGMENT_ATTRS) {
+        const v = attrs[k];
+        if (typeof v === "string" && v) {
+            const r = o.redact(`#${v.replace(/^#/, "")}`).slice(1);
+            if (r !== v)
+                set(k, r);
+        }
+    }
+    if (!o.captureClientIp) {
+        for (const k of CLIENT_IP_ATTRS)
+            if (k in attrs)
+                set(k, undefined);
+        if (o.isServer)
+            for (const k of SERVER_PEER_IP_ATTRS)
+                if (k in attrs)
+                    set(k, undefined);
+    }
+    return out ?? attrs;
+}

package/dist/web.d.ts

@@ -1,3 +1,4 @@
+import { type UrlRedactor } from "./redact.js";
 /** The replay chunk metadata sent alongside the events array. Defined locally so
  *  the published SDK does not depend on the private @heystack/schema package. */
 export interface ReplayChunkMeta {
@@ -130,6 +131,14 @@ export interface InstrumentWebOptions {
      * Rate-capped and recursion-guarded so it can never feed a self-export loop.
      */
     captureConsole?: "error" | "warn" | false;
+    /**
+     * Extra query/fragment parameter names whose values are replaced with
+     * `REDACTED` in every URL this SDK records (fetch spans, page URL on errors,
+     * console logs, bug reports and replay). Added to the built-in list (`token`,
+     * `code`, `key`, `apikey`, `access_token`, `signature`, …); userinfo is always
+     * stripped. Pass `false` to turn parameter redaction off.
+     */
+    redactQueryParams?: readonly string[] | false;
 }
 /**
  * Pure: is browser distributed tracing active for this run? Requires BOTH the app
@@ -146,6 +155,33 @@ export declare function tracingActive(opts: Pick<InstrumentWebOptions, "tracing"
  * (`cfg.errors_enabled`). **Fail-open**: an absent/`true` flag counts as enabled.
  */
 export declare function errorCaptureActive(opts: Pick<InstrumentWebOptions, "errors">, cfg: Pick<RecorderConfig, "errors_enabled">): boolean;
+/** rrweb `record()` privacy options for a masking mode. */
+export interface ReplayPrivacyOptions {
+    maskAllInputs: boolean;
+    maskTextSelector: string;
+    blockSelector: string;
+    maskInputFn: (text: string, element: HTMLElement) => string;
+    maskTextFn: (text: string, element: HTMLElement | null) => string;
+}
+/**
+ * Pure: the rrweb privacy options for a masking mode. Anything other than an
+ * explicit `"relaxed"` is treated as `"strict"` (fail-closed).
+ *
+ * - **strict** (default): ALL text and ALL input values are masked
+ *   (`maskTextSelector: "*"` + `maskAllInputs`). Mark an element with
+ *   `data-hs-unmask` to record it (and its descendants) in cleartext; a nested
+ *   `data-hs-mask` re-masks. Password inputs are ALWAYS masked, even inside a
+ *   `data-hs-unmask` region.
+ * - **relaxed**: text is recorded except inside `data-hs-mask`; input values are
+ *   recorded except passwords (rrweb's default).
+ *
+ * Both modes drop `data-hs-block` elements entirely (recorded as a placeholder
+ * box). Masking applies to text nodes and input values only — element ATTRIBUTES
+ * (`title`, `alt`, `placeholder`, `aria-label`, link `href`s) are not masked by
+ * rrweb, so use `data-hs-block` for regions whose attributes are sensitive.
+ */
+export declare function replayPrivacyOptions(mode: RecorderConfig["masking_mode"] | undefined): ReplayPrivacyOptions;
+export declare function redactReplayEvent(event: unknown, redact?: UrlRedactor): unknown;
 /** A caller-owned session UUID allows product activity to correlate with replay. */
 export declare function resolveWebSessionId(candidate?: string): string;
 /** Entry point: fetch config, decide sampling, start rrweb, stream chunks.
@@ -236,6 +272,8 @@ export interface TracingPatchOpts {
     /** Cross-origin backends allowed to receive trace headers (same-origin always is).
      *  Third-party / non-listed cross-origin calls are passed through untouched. */
     propagateTargets?: ReadonlyArray<string | RegExp>;
+    /** URL redactor for the recorded `url.full` (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
     rng?: () => number;
 }
 /** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
@@ -322,6 +360,8 @@ export interface ErrorCaptureOpts {
     rateCap?: number;
     /** Rate window in ms (default 60_000). */
     rateWindowMs?: number;
+    /** URL redactor for the recorded page URL (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
 }
 /** Wire up `window.onerror` / `unhandledrejection` (+ optional console) capture.
  *  Returns an unpatch function. Recursion-guarded (anything logged on our own
@@ -356,6 +396,8 @@ export interface BugReportSession {
     logsExporter: BrowserLogsExporter;
     version?: string;
     build?: string;
+    /** URL redactor for the attached page URL (default: built-in redaction). */
+    redactUrl?: UrlRedactor;
 }
 /** Internal: instrumentWeb() registers the active session here (and clears it with
  *  `null` on stop) so the module-level reportBug() works after instrumentWeb() is

package/dist/web.js

@@ -3,6 +3,8 @@ import { DEFAULT_ENDPOINT, releaseResourceAttributes } from "./core.js";
 // bundle. Used to skip tracing our OWN telemetry POSTs (the self-export loop that
 // caused the June 2026 cost incident); see CLAUDE.md → "Cost guardrails".
 import { safeHostname } from "./self-span.js";
+// Pure, import-free URL redaction shared with the server entries.
+import { makeUrlRedactor, redactUrl } from "./redact.js";
 /** Pure: decide once per session whether to record. rng defaults to Math.random. */
 export function shouldRecord(cfg, rng = Math.random) {
     if (!cfg.enabled)
@@ -100,6 +102,72 @@ export function tracingActive(opts, cfg) {
 export function errorCaptureActive(opts, cfg) {
     return opts.errors !== false && cfg.errors_enabled !== false;
 }
+const MASK_ATTR = "data-hs-mask";
+const UNMASK_ATTR = "data-hs-unmask";
+/** True if the NEAREST `data-hs-mask` / `data-hs-unmask` marker on `element` or
+ *  an ancestor is `data-hs-unmask` (so a `data-hs-mask` nested inside an unmasked
+ *  region re-masks). */
+function isRevealed(element) {
+    const marked = element?.closest?.(`[${MASK_ATTR}],[${UNMASK_ATTR}]`);
+    return !!marked && !!marked.hasAttribute?.(UNMASK_ATTR);
+}
+function isPasswordInput(element) {
+    const type = (element?.type ?? element?.getAttribute?.("type") ?? "").toString().toLowerCase();
+    return type === "password";
+}
+const stars = (text) => "*".repeat(text.length);
+/**
+ * Pure: the rrweb privacy options for a masking mode. Anything other than an
+ * explicit `"relaxed"` is treated as `"strict"` (fail-closed).
+ *
+ * - **strict** (default): ALL text and ALL input values are masked
+ *   (`maskTextSelector: "*"` + `maskAllInputs`). Mark an element with
+ *   `data-hs-unmask` to record it (and its descendants) in cleartext; a nested
+ *   `data-hs-mask` re-masks. Password inputs are ALWAYS masked, even inside a
+ *   `data-hs-unmask` region.
+ * - **relaxed**: text is recorded except inside `data-hs-mask`; input values are
+ *   recorded except passwords (rrweb's default).
+ *
+ * Both modes drop `data-hs-block` elements entirely (recorded as a placeholder
+ * box). Masking applies to text nodes and input values only — element ATTRIBUTES
+ * (`title`, `alt`, `placeholder`, `aria-label`, link `href`s) are not masked by
+ * rrweb, so use `data-hs-block` for regions whose attributes are sensitive.
+ */
+export function replayPrivacyOptions(mode) {
+    const strict = mode !== "relaxed";
+    if (!strict) {
+        return {
+            maskAllInputs: false,
+            maskTextSelector: `[${MASK_ATTR}]`,
+            blockSelector: "[data-hs-block]",
+            // rrweb only calls these for nodes it already decided to mask
+            // (`data-hs-mask` text / password inputs) — always mask them.
+            maskInputFn: (text) => stars(text),
+            maskTextFn: (text) => stars(text),
+        };
+    }
+    return {
+        maskAllInputs: true,
+        // "*" matches every element, so rrweb routes ALL text through maskTextFn
+        // (rrweb 2.0.1 checks `el.closest(maskTextSelector)` for mutations and
+        // `el.matches(...)` / ancestor checks for snapshots).
+        maskTextSelector: "*",
+        blockSelector: "[data-hs-block]",
+        maskInputFn: (text, element) => !isPasswordInput(element) && isRevealed(element) ? text : stars(text),
+        maskTextFn: (text, element) => (isRevealed(element) ? text : stars(text)),
+    };
+}
+/** rrweb Meta events (`type: 4`) carry the page `href`: return a copy with it redacted. */
+const META = 4;
+export function redactReplayEvent(event, redact = redactUrl) {
+    const e = event;
+    if (e && e.type === META && e.data && typeof e.data.href === "string") {
+        const href = redact(e.data.href);
+        if (href !== e.data.href)
+            return { ...e, data: { ...e.data, href } };
+    }
+    return event;
+}
 /** A caller-owned session UUID allows product activity to correlate with replay. */
 export function resolveWebSessionId(candidate) {
     if (candidate === undefined)
@@ -136,6 +204,8 @@ export async function instrumentWeb(opts) {
     const sessionId = resolveWebSessionId(opts.sessionId);
     // service.version / service.build for release attribution on exported browser logs.
     const releaseAttrs = releaseResourceAttributes({ version: opts.version, build: opts.build });
+    // One URL redactor for everything this run records (spans, logs, replay).
+    const redact = makeUrlRedactor(opts);
     // 2. Browser distributed tracing (opt-in) — INDEPENDENT of replay sampling. Emits
     //    a real CLIENT span per outbound fetch + propagates W3C context to the backend.
     let stopTracing = () => { };
@@ -154,6 +224,7 @@ export async function instrumentWeb(opts) {
             collector: traces, // real trace ids also tag the replay session (better correlation)
             activeTrace, // so a captured error can reference the in-flight span
             propagateTargets: opts.tracePropagationTargets, // same-origin + these only (never third parties)
+            redactUrl: redact,
         });
         fetchPatched = true;
         const traceFlush = setInterval(() => void exporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
@@ -181,7 +252,7 @@ export async function instrumentWeb(opts) {
     registerBugSession({
         endpoint, apiKey: opts.apiKey, service: opts.service, sessionId,
         fetchImpl: originalFetch, activeTrace, recentErrors, logsExporter,
-        version: opts.version, build: opts.build,
+        version: opts.version, build: opts.build, redactUrl: redact,
     });
     // 2b. Browser error / console log collection — ON by default, INDEPENDENT of both
     //     tracing and replay sampling. Exports OTLP logs to /v1/logs via the original fetch.
@@ -195,6 +266,7 @@ export async function instrumentWeb(opts) {
             captureConsole: opts.captureConsole ?? "error",
             activeTrace,
             recent: recentErrors,
+            redactUrl: redact,
         });
         const logFlush = setInterval(() => void logsExporter.flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
         const onHideLogs = () => { if (document.visibilityState === "hidden")
@@ -214,16 +286,11 @@ export async function instrumentWeb(opts) {
     if (!shouldRecord(cfg))
         return () => { stopTracing(); stopErrors(); registerBugSession(null); };
     const { record } = await import("rrweb");
-    // An element marked `data-hs-unmask` (or any descendant of one) is recorded in
-    // cleartext; everything else is masked. rrweb 2.0.1's real opt-out hooks are
-    // `maskInputFn`/`maskTextFn` — there is no `unmaskTextSelector` option.
-    // Signatures (from rrweb-snapshot 2.0.1):
-    //   MaskInputFn = (text: string, element: HTMLElement) => string
-    //   MaskTextFn  = (text: string, element: HTMLElement | null) => string
-    // `maskTextFn`'s element can be null, so the `?.closest?.` chain is guarded.
-    const reveal = (text, element) => !!element?.closest?.("[data-hs-unmask]");
-    const maskInputFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
-    const maskTextFn = (text, element) => reveal(text, element) ? text : "*".repeat(text.length);
+    // Strict (the default, and the fallback for any unknown/missing mode) masks ALL
+    // text and input values; `data-hs-unmask` opts an element back in. rrweb 2.0.1
+    // has no `unmaskTextSelector`, so the opt-out is implemented in
+    // `maskTextFn`/`maskInputFn` — see replayPrivacyOptions.
+    const privacy = replayPrivacyOptions(cfg.masking_mode);
     const transport = new ReplayTransport({ endpoint, apiKey: opts.apiKey, fetchImpl: originalFetch, sessionId });
     // Only patch fetch for replay correlation if tracing didn't already patch it
     // (tracing's patch injects real context AND feeds `traces`). Avoids double-wrapping
@@ -244,7 +311,7 @@ export async function instrumentWeb(opts) {
         const errs = errorCount;
         errorCount = 0;
         void transport.send(events, {
-            url: location.href, errorCount: errs, userId: opts.userId, browser, device,
+            url: redact(location.href), errorCount: errs, userId: opts.userId, browser, device,
             traceIds: traces.drain(),
         }, keepalive);
     };
@@ -256,17 +323,13 @@ export async function instrumentWeb(opts) {
             // nearest keyframe ≤ a target time instead of loading the whole session.
             if (isCheckout)
                 flush();
-            buffer.push(event);
+            buffer.push(redactReplayEvent(event, redact));
             if (buffer.length >= (opts.flushEveryEvents ?? DEFAULT_FLUSH_EVENTS))
                 flush();
         },
         // A ~60s keyframe cadence bounds how many chunks the player must fetch to seek.
         checkoutEveryNms: 60_000,
-        maskAllInputs: cfg.masking_mode === "strict",
-        maskTextSelector: "[data-hs-mask]",
-        blockSelector: "[data-hs-block]",
-        maskInputFn,
-        maskTextFn,
+        ...privacy,
     });
     const interval = setInterval(() => flush(), opts.flushIntervalMs ?? DEFAULT_FLUSH_MS);
     const onHide = () => { if (document.visibilityState === "hidden")
@@ -460,11 +523,13 @@ function fetchMethod(input, init) {
     return m.toUpperCase();
 }
 function pathOf(url) {
+    // Relative URLs (no base) fall back to the raw string minus query/fragment, so a
+    // span NAME never carries a secret the url.full redaction removed.
     try {
         return new URL(url).pathname;
     }
     catch {
-        return url;
+        return url.split(/[?#]/)[0] ?? url;
     }
 }
 /** Patch window.fetch to emit a real CLIENT span per outbound call, inject that
@@ -475,6 +540,7 @@ export function patchFetchForTracing(o) {
         return () => { };
     const orig = window.fetch.bind(window);
     const rng = o.rng ?? Math.random;
+    const redact = o.redactUrl ?? redactUrl;
     window.fetch = ((input, init) => {
         const url = fetchUrl(input);
         // Never trace our own telemetry POSTs (trace export, replay upload, config) —
@@ -502,7 +568,7 @@ export function patchFetchForTracing(o) {
         const emit = (statusCode, error) => {
             if (!sampled)
                 return;
-            o.onSpan({ traceId, spanId, name: `${method} ${pathOf(url)}`, startMs, endMs: Date.now(), method, url, statusCode, error });
+            o.onSpan({ traceId, spanId, name: `${method} ${pathOf(url)}`, startMs, endMs: Date.now(), method, url: redact(url), statusCode, error });
         };
         return orig(input, { ...init, headers }).then((res) => { emit(res.status, res.status >= 400); return res; }, (err) => { emit(0, true); throw err; });
     });
@@ -647,6 +713,7 @@ export function startErrorCapture(o) {
     if (typeof window === "undefined")
         return () => { };
     const now = o.now ?? Date.now;
+    const redact = o.redactUrl ?? redactUrl;
     const gate = new RateGate(o.rateCap ?? 60, o.rateWindowMs ?? 60_000, now);
     // Re-entrancy flag: if capturing a record ends up invoking a patched console
     // (or any path that re-enters here), we drop the nested call — this is what
@@ -677,7 +744,7 @@ export function startErrorCapture(o) {
             o.recent?.push({ message: e.message, type: e.type, timestamp: now() });
             const attrs = {
                 "event.name": "browser.error",
-                "url.full": location.href,
+                "url.full": redact(location.href),
                 session_id: o.sessionId,
                 "exception.message": e.message,
             };
@@ -740,7 +807,7 @@ export function startErrorCapture(o) {
                     attributes: {
                         "event.name": "browser.console",
                         "console.level": level,
-                        "url.full": location.href,
+                        "url.full": redact(location.href),
                         session_id: o.sessionId,
                     },
                     traceId: active?.traceId,
@@ -778,7 +845,7 @@ export function buildBugReportPayload(s, report) {
         message: report.message,
         email: report.email,
         context: report.context,
-        url: typeof location !== "undefined" ? location.href : undefined,
+        url: typeof location !== "undefined" ? (s.redactUrl ?? redactUrl)(location.href) : undefined,
         user_agent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
         session_id: s.sessionId,
         trace_id: active?.traceId,
@@ -821,7 +888,7 @@ export async function reportBug(report) {
         body: message,
         attributes: {
             "event.name": "user.bug_report",
-            "url.full": typeof location !== "undefined" ? location.href : "",
+            "url.full": typeof location !== "undefined" ? (s.redactUrl ?? redactUrl)(location.href) : "",
             session_id: s.sessionId,
             ...(report.email ? { "user.email": report.email } : {}),
         },

package/dist/workers-bindings.d.ts

@@ -1,4 +1,5 @@
 import { SpanKind, type Span } from "@opentelemetry/api";
+import type { BindingKind } from "./workers-coverage.js";
 export interface InstrumentBindingsOpts {
     /**
      * Factory that creates and starts a new child span. Called at binding method
@@ -8,7 +9,17 @@ export interface InstrumentBindingsOpts {
      * For integration: pass `(name, attrs, kind) => tracer.startSpan(name, { attributes: attrs, kind }, context.active())`.
      * For unit tests: inject a fake so no global provider is required.
      */
-    startSpan: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
+    startSpan?: (name: string, attrs: Record<string, unknown>, kind?: SpanKind) => Span;
+    /**
+     * Callback-scoped span runner (native mode). When present, every wrapper runs
+     * its operation inside it and `startSpan` is never called. Must throw/reject
+     * only what `fn` throws.
+     */
+    withSpan?: <T>(name: string, attrs: Record<string, unknown>, kind: SpanKind | undefined, fn: (span: Span) => T | Promise<T>) => Promise<T>;
+    /** Skip bindings whose {@link BindingKind} this returns false for. */
+    kindFilter?: (kind: BindingKind) => boolean;
+    /** Use Cloudflare-native span names (`ai_run`, `vectorize_<op>`, `workflow_<op>`, ...). */
+    nativeNames?: boolean;
     /**
      * `true`  → auto-detect and wrap every supported Cloudflare binding.
      * `string[]` → only wrap bindings whose env key is listed.
@@ -21,6 +32,19 @@ export interface InstrumentBindingsOpts {
  * wrappers in workers.ts.
  */
 export declare function runWithSpan<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+/** Plain string keys from a string / string[] argument (anything else yields none). */
+export declare function keysOf(value: unknown): string[];
+/** Resolves once every in-flight key hash has attached its attribute and ended its span. */
+export declare function settlePendingKeyHashes(): Promise<void>;
+/**
+ * Like {@link runWithSpan} for operations that carry user-controlled keys. The
+ * hash is computed concurrently with the call and attached under `attr` before
+ * the span ends; it can neither delay the call's result nor change its error.
+ * If hashing is impossible the attribute is omitted (never the raw key).
+ */
+export declare function runWithSpanKeyed<T>(span: Span, attr: string, keys: readonly string[], fn: () => Promise<T>, countAttr?: string): Promise<T>;
+/** Trace a call without replacing synchronous, Promise, or custom thenable results. */
+export declare function runWithSpanPreservingReturn<T>(span: Span, fn: () => T): T;
 /** Internal proxy builder shared with the class-level wrappers in workers.ts. */
 export declare function makeProxy(target: any, handlers: Record<string, Function>): any;
 /**
@@ -61,4 +85,17 @@ export declare function injectTraceparentArgs(args: any[], traceparent: string):
  * @param opts - `startSpan` factory (now accepts optional `SpanKind`) + `select` filter.
  * @returns A shallow copy of `env` with selected bindings replaced by proxies.
  */
-export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, opts: InstrumentBindingsOpts): E;
+export declare function instrumentEnv<E extends Record<string, unknown>>(env: E, rawOpts: InstrumentBindingsOpts): E;
+/**
+ * Wrap a Postgres/MySQL client (postgres.js, pg, mysql2, ...) created from a
+ * Hyperdrive binding so each `query` / `unsafe` / `execute` call, and each
+ * tagged-template call when the client itself is callable (postgres.js
+ * `sql\`select 1\``), emits a `hyperdrive_query` span. `db.query.text` is
+ * recorded raw (template strings are joined with `?`; ingest sanitises). The
+ * ORIGINAL return value is passed through untouched; the span ends when it
+ * settles. Uses the request's native tracer when present, else the global one.
+ */
+export declare function wrapSqlClient<C extends object>(client: C, opts?: {
+    name?: string;
+    dbSystem?: "postgresql" | "mysql";
+}): C;