@belvador/core 0.1.0 → 0.3.0

package/dist/monitor.js

@@ -0,0 +1,330 @@
+// Monitors (build observability-1.0 spec 06 §2–§4, RLY-25): check-ins on Sentry's wire
+// (develop.sentry.dev/sdk/telemetry/check-ins) plus Belvador's versioned run context.
+// `withMonitor` never changes what the app's function returns or throws, never adds an
+// await to a synchronous function, and a failed send never fails the job.
+import { captureException as engineCaptureException, createCheckInEnvelope, getActiveSpan, getClient, getCurrentScope, getTraceContextFromScope, spanToTraceContext, uuid4, withIsolationScope, } from "@sentry/core";
+import { reportDiagnostic } from "./diagnostics.js";
+import { isActive } from "./facade.js";
+// Copies of `src/shared/contracts/monitors.ts` (a root test keeps them equal).
+export const MONITOR_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const RUN_REASON_RE = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+export const RUN_CONTEXT = "belvador_run";
+export const MONITOR_CONTEXT = "monitor";
+export const MONITOR_CONFIG_LIMITS = {
+    intervalValueMax: 1000,
+    checkinMarginMax: 1440,
+    maxRuntimeMax: 10080,
+    thresholdMax: 720,
+    environmentMax: 64,
+    attemptMax: 1000,
+};
+export const INTERVAL_UNITS = ["minute", "hour", "day", "week", "month", "year"];
+const HEX32 = /^[0-9a-f]{32}$/;
+const DASHED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** A UUID as 32 lowercase hex; any other id maps to a stable UUID-shaped hash (grouping only). */
+export function runIdOf(value) {
+    const v = value.trim().toLowerCase();
+    if (HEX32.test(v))
+        return v;
+    if (DASHED.test(v))
+        return v.replace(/-/g, "");
+    // Two 64-bit FNV-1a lanes → 128 bits; not a security boundary, only "same id → same run".
+    let a = 0xcbf29ce484222325n;
+    let b = 0x84222325cbf29ce4n;
+    const prime = 0x100000001b3n;
+    const mask = (1n << 64n) - 1n;
+    for (let i = 0; i < value.length; i++) {
+        const c = BigInt(value.charCodeAt(i));
+        a = ((a ^ c) * prime) & mask;
+        b = ((b ^ (c + 0x9en)) * prime) & mask;
+    }
+    return a.toString(16).padStart(16, "0") + b.toString(16).padStart(16, "0");
+}
+function validTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function intIn(v, min, max) {
+    return v === undefined || (typeof v === "number" && Number.isInteger(v) && v >= min && v <= max);
+}
+/** Wire `monitor_config`, or null (with a diagnostic) when anything is invalid. */
+export function monitorConfigOf(input) {
+    if (!input || input.schedule === undefined)
+        return null;
+    try {
+        const s = input.schedule;
+        let schedule = null;
+        if (s && s.type === "crontab" && typeof s.value === "string") {
+            const fields = s.value.trim().split(/\s+/);
+            if (s.value.length <= 120 && fields.length === 5 && fields.every((f) => /^[0-9A-Za-z*,/?#LW-]+$/.test(f)))
+                schedule = { type: "crontab", value: fields.join(" ") };
+        }
+        else if (s &&
+            s.type === "interval" &&
+            intIn(s.value, 1, MONITOR_CONFIG_LIMITS.intervalValueMax) &&
+            INTERVAL_UNITS.includes(s.unit)) {
+            schedule = { type: "interval", value: s.value, unit: s.unit };
+        }
+        const tz = input.timezone ?? "UTC";
+        const ok = schedule !== null &&
+            typeof tz === "string" &&
+            tz.length > 0 &&
+            tz.length <= 64 &&
+            validTimeZone(tz) &&
+            intIn(input.checkinMargin, 1, MONITOR_CONFIG_LIMITS.checkinMarginMax) &&
+            // Larger than Sentry's 7-day ceiling is clamped by the node, like Sentry.
+            intIn(input.maxRuntime, 1, Number.MAX_SAFE_INTEGER) &&
+            intIn(input.failureIssueThreshold, 1, MONITOR_CONFIG_LIMITS.thresholdMax) &&
+            intIn(input.recoveryThreshold, 1, MONITOR_CONFIG_LIMITS.thresholdMax);
+        if (!ok) {
+            reportDiagnostic("BLV_MONITOR_CONFIG_INVALID");
+            return null;
+        }
+        const out = { schedule, timezone: tz };
+        if (input.checkinMargin !== undefined)
+            out["checkin_margin"] = input.checkinMargin;
+        if (input.maxRuntime !== undefined)
+            out["max_runtime"] = input.maxRuntime;
+        if (input.failureIssueThreshold !== undefined)
+            out["failure_issue_threshold"] = input.failureIssueThreshold;
+        if (input.recoveryThreshold !== undefined)
+            out["recovery_threshold"] = input.recoveryThreshold;
+        return out;
+    }
+    catch {
+        reportDiagnostic("BLV_MONITOR_CONFIG_INVALID");
+        return null;
+    }
+}
+function cleanReason(reason) {
+    if (reason === undefined)
+        return undefined;
+    if (typeof reason === "string" && RUN_REASON_RE.test(reason))
+        return reason;
+    reportDiagnostic("BLV_MONITOR_INVALID_REASON");
+    return undefined;
+}
+function now() {
+    try {
+        return typeof performance !== "undefined" && typeof performance.now === "function"
+            ? performance.now()
+            : Date.now();
+    }
+    catch {
+        return Date.now();
+    }
+}
+/** The check-in item exactly as sent (exported for the golden test). */
+export function buildCheckIn(input, client, config, trace) {
+    const options = client.getOptions();
+    const id = input.checkInId ? runIdOf(input.checkInId) : uuid4();
+    const env = typeof input.environment === "string" && input.environment.trim() ? input.environment.trim() : options.environment;
+    const run = { v: 1 };
+    if (input.runId)
+        run["run_id"] = runIdOf(input.runId);
+    if (intIn(input.attempt, 1, MONITOR_CONFIG_LIMITS.attemptMax) && input.attempt !== undefined)
+        run["attempt"] = input.attempt;
+    if (input.willRetry === true && input.status === "error")
+        run["will_retry"] = true;
+    if (input.outcome && input.status !== "in_progress")
+        run["outcome"] = input.outcome;
+    const reason = cleanReason(input.reason);
+    if (reason)
+        run["reason"] = reason;
+    const item = {
+        check_in_id: id,
+        monitor_slug: input.monitorSlug,
+        status: input.status,
+    };
+    if (input.status !== "in_progress" && typeof input.duration === "number" && Number.isFinite(input.duration) && input.duration >= 0)
+        item.duration = input.duration;
+    if (options.release)
+        item.release = options.release;
+    if (env)
+        item.environment = String(env).slice(0, MONITOR_CONFIG_LIMITS.environmentMax);
+    if (config)
+        item["monitor_config"] = config;
+    const contexts = {};
+    if (trace)
+        contexts["trace"] = { trace_id: trace.trace_id, span_id: trace.span_id };
+    if (Object.keys(run).length > 1)
+        contexts[RUN_CONTEXT] = run;
+    if (Object.keys(contexts).length)
+        item["contexts"] = contexts;
+    return item;
+}
+function send(item, client) {
+    try {
+        const envelope = createCheckInEnvelope(item, undefined, client.getSdkMetadata(), client.getOptions().tunnel, client.getDsn());
+        Promise.resolve(client.sendEnvelope(envelope)).then(undefined, () => undefined);
+    }
+    catch {
+        reportDiagnostic("BLV_CHECK_IN_DROPPED");
+    }
+}
+/** The trace errors of this scope carry: the active (request) span's, else the scope's. */
+function currentTrace() {
+    try {
+        const span = getActiveSpan();
+        const t = span ? spanToTraceContext(span) : getTraceContextFromScope(getCurrentScope());
+        return t?.trace_id && t.span_id ? { trace_id: t.trace_id, span_id: t.span_id } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sends one check-in; returns its id ("" when the SDK is off or the slug is invalid). Never throws. */
+export function captureCheckIn(checkIn, monitorConfig) {
+    try {
+        if (!isActive())
+            return "";
+        const client = getClient();
+        if (!client)
+            return "";
+        if (typeof checkIn?.monitorSlug !== "string" || !MONITOR_SLUG_RE.test(checkIn.monitorSlug)) {
+            reportDiagnostic("BLV_MONITOR_INVALID_SLUG");
+            return "";
+        }
+        const item = buildCheckIn(checkIn, client, monitorConfigOf(monitorConfig), currentTrace());
+        send(item, client);
+        return String(item.check_in_id);
+    }
+    catch {
+        return "";
+    }
+}
+/** A healthy check-in for an interval monitor ("still alive"). */
+export function heartbeat(slug, options) {
+    captureCheckIn({ monitorSlug: slug, status: "ok", ...(options?.environment ? { environment: options.environment } : {}) });
+}
+function isThenable(v) {
+    return v !== null && (typeof v === "object" || typeof v === "function") && typeof v.then === "function";
+}
+/**
+ * Runs `fn` as one monitored attempt: `in_progress` first, then `ok` (or skipped/unknown
+ * via the handle) when it returns, or the error captured as a normal issue and `error`
+ * when it throws — the same value or error goes back to the caller, unchanged.
+ */
+export function withMonitor(slug, fn, options) {
+    const inert = { checkInId: "", runId: "", skip: () => undefined, unknown: () => undefined };
+    let ready = false;
+    let client;
+    try {
+        client = isActive() ? getClient() : undefined;
+        if (client && (typeof slug !== "string" || !MONITOR_SLUG_RE.test(slug))) {
+            reportDiagnostic("BLV_MONITOR_INVALID_SLUG");
+            client = undefined;
+        }
+        ready = client !== undefined;
+    }
+    catch {
+        ready = false;
+    }
+    if (!ready || !client)
+        return fn(inert);
+    const c = client;
+    const o = options ?? {};
+    let config = null;
+    try {
+        config = monitorConfigOf(o);
+    }
+    catch {
+        config = null;
+    }
+    const base = {
+        monitorSlug: slug,
+        ...(o.environment !== undefined ? { environment: o.environment } : {}),
+        ...(o.attempt !== undefined ? { attempt: o.attempt } : {}),
+    };
+    return withIsolationScope((scope) => {
+        let checkInId = "";
+        let runId = "";
+        let outcome = null;
+        let finished = false;
+        let started = 0;
+        try {
+            scope.setContext(MONITOR_CONTEXT, { slug });
+            checkInId = uuid4();
+            runId = o.runId ? runIdOf(o.runId) : checkInId;
+            started = now();
+            send(buildCheckIn({ ...base, status: "in_progress", checkInId, runId }, c, config, currentTrace()), c);
+        }
+        catch {
+            /* never stops the job */
+        }
+        const handle = {
+            checkInId,
+            runId,
+            skip: (reason) => {
+                if (!finished)
+                    outcome = { kind: "skipped", reason };
+            },
+            unknown: (reason) => {
+                if (!finished)
+                    outcome = { kind: "unknown", reason };
+            },
+        };
+        const finish = (status, error) => {
+            if (finished)
+                return;
+            finished = true;
+            try {
+                let willRetry = false;
+                if (status === "error") {
+                    try {
+                        willRetry = typeof o.willRetry === "function" ? o.willRetry(error) === true : o.willRetry === true;
+                    }
+                    catch {
+                        willRetry = false;
+                    }
+                }
+                const done = outcome;
+                send(buildCheckIn({
+                    ...base,
+                    status,
+                    checkInId,
+                    runId,
+                    duration: Math.max(0, (now() - started) / 1000),
+                    ...(willRetry ? { willRetry } : {}),
+                    ...(status === "ok" && done ? { outcome: done.kind, reason: done.reason } : {}),
+                }, c, config, currentTrace()), c);
+            }
+            catch {
+                /* never stops the job */
+            }
+        };
+        const failed = (error) => {
+            try {
+                engineCaptureException(error);
+            }
+            catch {
+                /* reported or not, the error goes back unchanged */
+            }
+            finish("error", error);
+        };
+        let result;
+        try {
+            result = fn(handle);
+        }
+        catch (error) {
+            failed(error);
+            throw error;
+        }
+        if (isThenable(result)) {
+            return result.then((value) => {
+                finish("ok");
+                return value;
+            }, (error) => {
+                failed(error);
+                throw error;
+            });
+        }
+        finish("ok");
+        return result;
+    });
+}

package/dist/options.d.ts

@@ -1,4 +1,6 @@
 import type { Breadcrumb, BreadcrumbHint, ErrorEvent, EventHint } from "@sentry/core";
+import { type Diagnostic } from "./diagnostics.js";
+import { type TracePropagationOptions } from "./trace.js";
 import { type SendPolicy } from "./transport.js";
 export type BelvadorEvent = ErrorEvent;
 export type BelvadorEventHint = EventHint;
@@ -19,12 +21,35 @@ export type BelvadorOptions = {
     /** Default 50, at most 100. */
     maxBreadcrumbs?: number;
     ignoreErrors?: Array<string | RegExp>;
+    /**
+     * Also report errors from work the client cancelled: an `AbortError` (fetch or stream
+     * aborted), or a server error thrown after the visitor closed the connection. Default
+     * false — cancellations are expected and never become issues. A `TimeoutError` is not
+     * a cancellation and is always reported.
+     */
+    captureAborted?: boolean;
+    /**
+     * Browsers: also report a View Transition the browser skipped on purpose (page hidden,
+     * another transition started, `skipTransition()`). Default false — these are expected.
+     */
+    captureViewTransitionSkips?: boolean;
+    /**
+     * Link errors and job check-ins across services with one trace id. Off by default:
+     * requests whose URL matches `targets` get `traceparent` + `sentry-trace` headers
+     * (the receiving API must allow them in CORS). No spans or transactions are sent.
+     */
+    tracePropagation?: TracePropagationOptions;
     /** Send attachments added with scope.addAttachment (each ≤ 5 MB). Default false. */
     attachments?: boolean;
     /** Runs before Belvador's own scrubbing; return null to drop the event. */
     beforeSend?: (event: BelvadorEvent, hint: BelvadorEventHint) => BelvadorEvent | null | PromiseLike<BelvadorEvent | null>;
     /** Runs before Belvador's own scrubbing; return null to drop the breadcrumb. */
     beforeBreadcrumb?: (crumb: BelvadorBreadcrumb, hint?: BreadcrumbHint) => BelvadorBreadcrumb | null;
+    /**
+     * Local diagnostics (missing DSN, refused key, failed sends, …): at most once a
+     * minute per code, never sent anywhere. Errors thrown here are ignored.
+     */
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
 };
 export type RuntimeName = "browser" | "react" | "cloudflare" | "tanstack-start";
 export declare const DEFAULT_MAX_BREADCRUMBS = 50;
@@ -60,6 +85,7 @@ export declare function buildEngineOptions(opts: BelvadorOptions, runtime: Runti
     defaultIntegrations: false;
     transport: (options: import("@sentry/core").BaseTransportOptions) => import("@sentry/core").Transport;
     _belvador: boolean;
+    _belvadorTrace: import("./trace.js").TraceConfig | null;
     _metadata: {
         sdk: {
             name: string;

package/dist/options.js

@@ -1,5 +1,9 @@
+import { isClientAbort, isViewTransitionSkip } from "./aborts.js";
+import { configureDiagnostics, reportDiagnostic } from "./diagnostics.js";
 import { checkDsn } from "./dsn.js";
 import { scrubBreadcrumb, scrubEvent } from "./privacy.js";
+import { VERIFICATION_CONTEXT, VERIFICATION_TAG, noteVerificationOutcome, verificationOf, } from "./verification.js";
+import { TRACE_OPTION, traceConfigOf } from "./trace.js";
 import { makeBelvadorTransport } from "./transport.js";
 import { ENGINE_VERSION, SDK_VERSION } from "./version.js";
 /** Engine package behind each runtime (for `sdk.packages`). */
@@ -30,19 +34,49 @@ export function warnOnce(message) {
 function clamp(n, min, max, fallback) {
     return typeof n === "number" && Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
 }
-function chainBeforeSend(user) {
+function chainBeforeSend(user, captureAborted, captureViewTransitionSkips) {
     return (event, hint) => {
+        // Integration health: a verification error carries its own tag and context; they are
+        // set before the app's beforeSend and restored after scrubbing (ids are not user data).
+        const v = verificationOf(hint?.originalException);
+        const original = hint?.originalException;
+        // A skipped View Transition is the standard working as designed (spec 03 §8).
+        if (!v && !captureViewTransitionSkips && isViewTransitionSkip(original))
+            return null;
+        // Cancelled by the client: expected, dropped before the app's hook (not a diagnostic).
+        // An opted-in View Transition skip is reported even though it is an AbortError.
+        if (!v && !captureAborted && isClientAbort(original) && !(captureViewTransitionSkips && isViewTransitionSkip(original)))
+            return null;
+        const mark = (e) => {
+            if (!v)
+                return e;
+            e.tags = { ...(e.tags ?? {}), [VERIFICATION_TAG]: v.id };
+            e.contexts = { ...(e.contexts ?? {}), [VERIFICATION_CONTEXT]: { ...v.context } };
+            return e;
+        };
+        const finish = (e) => {
+            if (!e) {
+                if (v) {
+                    noteVerificationOutcome(v.id, v.context.check, { kind: "dropped" });
+                    reportDiagnostic("BLV_DROPPED_BY_APP");
+                }
+                return null;
+            }
+            // A scrubber failure drops the event (never sends it unscrubbed).
+            const clean = scrubEvent(e);
+            return clean ? mark(clean) : null;
+        };
         let out;
         try {
-            out = user ? user(event, hint) : event;
+            out = user ? user(mark(event), hint) : mark(event);
         }
         catch {
-            return null;
+            return finish(null);
         }
         if (out && typeof out.then === "function") {
-            return Promise.resolve(out).then((e) => (e ? scrubEvent(e) : null), () => null);
+            return Promise.resolve(out).then(finish, () => finish(null));
         }
-        return out ? scrubEvent(out) : null;
+        return finish(out);
     };
 }
 function chainBeforeBreadcrumb(user) {
@@ -63,9 +97,22 @@ function chainBeforeBreadcrumb(user) {
 export function buildEngineOptions(opts, runtime, send) {
     if (!opts || opts.disabled === true)
         return null;
+    const sdkName = `belvador.javascript.${runtime}`;
     const dsn = checkDsn(opts.dsn);
+    configureDiagnostics({
+        onDiagnostic: typeof opts.onDiagnostic === "function" ? opts.onDiagnostic : undefined,
+        debug: opts.debug === true,
+        sdk: { name: sdkName, version: SDK_VERSION },
+        dsn: dsn
+            ? { host: dsn.host, project: dsn.projectId, keyHint: dsn.publicKey.slice(0, 4) }
+            : null,
+    });
     if (!dsn) {
-        warnOnce("invalid DSN — the SDK is off. Copy the DSN from your Belvador project settings.");
+        const missing = typeof opts.dsn !== "string" || opts.dsn.trim() === "";
+        reportDiagnostic(missing ? "BLV_DSN_MISSING" : "BLV_DSN_INVALID");
+        warnOnce(missing
+            ? "no DSN — the SDK is off. Copy the DSN from your Belvador project settings."
+            : "invalid DSN — the SDK is off. Copy the DSN from your Belvador project settings.");
         return null;
     }
     const attachments = opts.attachments === true;
@@ -86,15 +133,17 @@ export function buildEngineOptions(opts, runtime, send) {
         // Never read SENTRY_TUNNEL / spotlight from the environment; events go only to the DSN.
         tunnel: "",
         spotlight: false,
-        beforeSend: chainBeforeSend(opts.beforeSend),
+        beforeSend: chainBeforeSend(opts.beforeSend, opts.captureAborted === true, opts.captureViewTransitionSkips === true),
         beforeBreadcrumb: chainBeforeBreadcrumb(opts.beforeBreadcrumb),
         beforeSendTransaction: () => null,
         defaultIntegrations: false,
         transport: makeBelvadorTransport({ ...send, attachments, debug: opts.debug === true }),
         [BELVADOR_MARKER]: true,
+        // Checked trace propagation of this client (null = off); the engine itself never adds headers.
+        [TRACE_OPTION]: traceConfigOf(opts.tracePropagation),
         _metadata: {
             sdk: {
-                name: `belvador.javascript.${runtime}`,
+                name: sdkName,
                 version: SDK_VERSION,
                 packages: [
                     { name: `npm:@belvador/${runtime}`, version: SDK_VERSION },

package/dist/privacy.d.ts

@@ -4,7 +4,7 @@ export declare const SENSITIVE_KEY_PARTS: readonly string[];
 export declare function isSensitiveKey(key: string): boolean;
 /** Credentials in URLs and `name=value` text: userinfo removed, sensitive parameter values filtered. */
 export declare function scrubParams(text: string): string;
-/** Every rule for free text: parameters, tokens, card numbers, emails. */
+/** Every rule for free text: assignments, parameters, tokens, card numbers, emails. */
 export declare function scrubText(text: string): string;
 /**
  * Bounded deep copy with every rule applied: sensitive keys → [Filtered],

package/dist/privacy.js

@@ -86,8 +86,15 @@ const EMAIL = /\b[A-Za-z0-9._%+-]{1,64}@([A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,6
 const USERINFO = /\b([a-z][a-z0-9+.-]{1,15}:\/\/)[^\s/?#@]+@/gi;
 /** name=value inside URLs, query strings and log lines. */
 const PARAM = /([A-Za-z0-9_.~%[\]-]{1,128})=([^&#\s"'<>,;]*)/g;
-/** "name": "value" inside JSON-looking text. */
-const JSON_PAIR = /"([^"\\]{1,128})"(\s*:\s*)"(?:[^"\\]|\\.)*"/g;
+/** `Basic <base64>` credentials in headers and log lines. */
+const BASIC_AUTH = /\bBasic\s+[A-Za-z0-9+/]{8,}={0,2}/g;
+/** "name": "value" / 'name': 'value' inside JSON- or dict-looking text (bounded, linear). */
+const QUOTED_ASSIGNMENT = /(["'])([^"'\\\n]{1,128})\1([ \t]{0,8}:[ \t]{0,8})(?:"((?:[^"\\\n]|\\.){0,1024})"|'((?:[^'\\\n]|\\.){0,1024})')/g;
+/**
+ * name=value, name => value and name: value in log lines; the value is one quoted string
+ * or one bare token. The name must not continue a longer word (the leading group).
+ */
+const ASSIGNMENT = /(^|[^A-Za-z0-9_.~%[\]-])([A-Za-z0-9_.~%[\]-]{1,128})([ \t]{0,8}(?:=>|=|:)[ \t]{0,8})("(?:[^"\\]|\\.){0,1024}"|'(?:[^'\\]|\\.){0,1024}'|[^\s&#"'<>,;{}()]{1,1024})/g;
 export function isSensitiveKey(key) {
     const lower = key.toLowerCase();
     for (const part of SENSITIVE_KEY_PARTS)
@@ -122,14 +129,27 @@ function luhn(digits) {
 export function scrubParams(text) {
     return text
         .replace(USERINFO, `$1${FILTERED}@`)
-        .replace(PARAM, (match, name) => isSensitiveKey(decodeName(name)) ? `${name}=${FILTERED}` : match);
+        // An empty value hides nothing (and a quoted value is left to the assignment rule).
+        .replace(PARAM, (match, name, value) => value !== "" && isSensitiveKey(decodeName(name)) ? `${name}=${FILTERED}` : match);
 }
-/** Every rule for free text: parameters, tokens, card numbers, emails. */
+/** Every rule for free text: assignments, parameters, tokens, card numbers, emails. */
 export function scrubText(text) {
     if (text.length === 0)
         return text;
     return scrubParams(text)
-        .replace(JSON_PAIR, (match, name, sep) => isSensitiveKey(name) ? `"${name}"${sep}"${FILTERED}"` : match)
+        .replace(BASIC_AUTH, `Basic ${FILTERED}`)
+        .replace(QUOTED_ASSIGNMENT, (match, q, name, sep, dq) => {
+        if (!isSensitiveKey(name))
+            return match;
+        const vq = dq !== undefined ? '"' : "'";
+        return `${q}${name}${q}${sep}${vq}${FILTERED}${vq}`;
+    })
+        .replace(ASSIGNMENT, (match, lead, name, sep, value) => {
+        if (!isSensitiveKey(decodeName(name)) || value === FILTERED)
+            return match;
+        const q = value[0] === '"' || value[0] === "'" ? value[0] : "";
+        return `${lead}${name}${sep}${q}${FILTERED}${q}`;
+    })
         .replace(BEARER, `Bearer ${FILTERED}`)
         .replace(PROVIDER_KEY, FILTERED)
         .replace(JWT, FILTERED)

package/dist/trace.d.ts

@@ -0,0 +1,32 @@
+export type TracePropagationOptions = {
+    /** URLs (substring) or RegExps; relative patterns match same-origin paths in browsers. Empty = off. */
+    targets?: Array<string | RegExp>;
+    /** Also send `baggage` (only the engine's `sentry-*` keys). Default false. */
+    baggage?: boolean;
+};
+export type TraceConfig = {
+    targets: Array<string | RegExp>;
+    baggage: boolean;
+};
+/** Engine-options key carrying the checked config of one client. */
+export declare const TRACE_OPTION = "_belvadorTrace";
+/** Valid targets only (others reported once a minute); null = propagation off. */
+export declare function traceConfigOf(opts: TracePropagationOptions | undefined): TraceConfig | null;
+/** W3C `traceparent` → `sentry-trace` (sampling left to the receiver), or null when invalid. */
+export declare function sentryTraceFromTraceparent(value: string | null | undefined): string | null;
+/**
+ * Server side: a request carrying a valid `traceparent` but no `sentry-trace` gets the
+ * equivalent `sentry-trace`, so the engine continues the same trace. Anything else is
+ * returned unchanged (same object).
+ */
+export declare function withIncomingTraceparent<R extends Request>(request: R): R;
+/** Sentry's rule: the whole URL, or (browsers) the path of a same-origin URL. */
+export declare function urlMatches(url: string, targets: ReadonlyArray<string | RegExp>): boolean;
+/**
+ * The current trace as headers: the active span's ids when there is one (a server request),
+ * else the scope's trace with a fresh span id. Errors-only, so the sampling flag is never set
+ * (`traceparent` flags 00, `sentry-trace` without the third part): the receiver decides.
+ */
+export declare function traceHeaders(baggage: boolean): Record<string, string> | null;
+/** Installs the fetch hook once per process; each client decides with its own config. */
+export declare function installTracePropagation(): void;