@apifuse/provider-sdk 2.2.0-beta.59 → 2.2.0-beta.60

package/dist/runtime/instrumentation.js

@@ -1,3 +1,4 @@
+import { registerDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
 import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
@@ -381,6 +382,7 @@ function wrapStealthRedirects(redirects, trace) {
         run(...args) {
             const diagnosticArgs = [args[0].url, args[0]];
             const diagnostics = snapshotRequestDiagnostics("stealth", "fetch", diagnosticArgs);
+            registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
             let result;
             try {
                 result = redirects.run(...args);
@@ -511,6 +513,7 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
                     return Reflect.apply(value, namespaceTarget, args);
                 }
                 const requestDiagnostics = snapshotRequestDiagnostics(namespace, methodName, args);
+                registerDiagnosticSensitiveValues(trace, requestDiagnostics.sensitiveValues);
                 // Invoke first and decide by the RETURN VALUE. `runSpan` always
                 // returns a Promise, so unconditionally span-wrapping every member
                 // silently rewrote synchronous contracts: `ctx.state.namespace()`

package/dist/runtime/ocr.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
 import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
@@ -55,7 +56,7 @@ export function createUnsupportedOcrClient(reason) {
     });
 }
 function normalizedEnvValue(env, key) {
-    const value = env[key]?.trim();
+    const value = readDiagnosticEnv(key, env)?.trim();
     return value ? value : undefined;
 }
 export function createOcrClientFromEnv(config, env = process.env) {

package/dist/runtime/otlp.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { AsyncResource } from "node:async_hooks";
 export const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
 export const OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT";
@@ -118,12 +119,12 @@ export function resolveOTLPExportOptions(explicit, env = process.env) {
         { source: EXPLICIT_ENDPOINT_SOURCE, value: explicit.endpoint, appendPath: false },
         {
             source: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
-            value: env[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT],
+            value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, env),
             appendPath: false,
         },
         {
             source: OTEL_EXPORTER_OTLP_ENDPOINT,
-            value: env[OTEL_EXPORTER_OTLP_ENDPOINT],
+            value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_ENDPOINT, env),
             appendPath: true,
         },
     ];
@@ -137,9 +138,9 @@ export function resolveOTLPExportOptions(explicit, env = process.env) {
         return { status: "invalid", source: candidate.source, reason: parsed.reason };
     }
     const endpoint = candidate.appendPath ? appendTracesPath(parsed.url) : candidate.value;
-    const tracesHeaders = presentValue(env[OTEL_EXPORTER_OTLP_TRACES_HEADERS]);
+    const tracesHeaders = presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_HEADERS, env));
     const headersSource = tracesHeaders !== undefined ? OTEL_EXPORTER_OTLP_TRACES_HEADERS : OTEL_EXPORTER_OTLP_HEADERS;
-    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(env[OTEL_EXPORTER_OTLP_HEADERS]));
+    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_HEADERS, env)));
     if (!headersAreSendable(envHeaders)) {
         return { status: "invalid", source: headersSource, reason: INVALID_HEADERS };
     }

package/dist/runtime/proxy-nodemaven.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, randomBytes } from "node:crypto";
 export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
 export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
@@ -25,10 +26,10 @@ export function hasNodemavenCredentials() {
     return Boolean(readNodemavenUsername() && readNodemavenPassword());
 }
 function readNodemavenUsername() {
-    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+    return readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)?.trim() || undefined;
 }
 function readNodemavenPassword() {
-    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+    return readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)?.trim() || undefined;
 }
 function resolveNodemavenFilter(value) {
     const raw = value?.trim().toLowerCase();

package/dist/runtime/request-options.d.ts

@@ -51,6 +51,13 @@ export declare function redactUrlQueryParams(url: string, sensitiveParamNames: r
  * separate, structurally redacted URL for diagnostics and observability.
  */
 export declare function serializeRequestUrl(url: string, params?: RequestParams, sensitiveParams?: Record<string, string>): SerializedRequestUrl;
+export declare function normalizePercentEscapes(value: string): string;
+export type SensitiveValueVariant = {
+    value: string;
+    requiresTokenBoundary: boolean;
+    caseInsensitive: boolean;
+};
+export declare function allSensitiveValueVariants(sensitiveValues: readonly string[]): SensitiveValueVariant[];
 /** Scrubs raw and URL-encoded secret values from diagnostic text. */
 export declare function redactSensitiveText(text: string, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): string;
 /**

package/dist/runtime/request-options.js

@@ -108,13 +108,33 @@ export function serializeRequestUrl(url, params, sensitiveParams) {
         sensitiveValues: [...sensitiveValues],
     };
 }
-const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 4;
-function normalizePercentEscapes(value) {
+const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 8;
+export function normalizePercentEscapes(value) {
     return value.replace(/%[\da-f]{2}/gi, (percentEscape) => percentEscape.toUpperCase());
 }
 function sensitiveValueVariants(value) {
     if (!value || value === REDACTED_QUERY_VALUE)
         return [];
+    // Owner-visible policy: short credentials are literal, case-sensitive tokens only.
+    // Encoded short needles collide with benign cursors and ordinary diagnostic text.
+    if (value.length < 8)
+        return [value];
+    // These ASCII characters are identical under NFC, JSON, URI-component and
+    // form encoding. Avoid constructing those identical variants for common tokens.
+    if (/^[A-Za-z0-9._*-]+$/.test(value)) {
+        const base64 = Buffer.from(value, "utf8").toString("base64");
+        const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+        return [
+            ...new Set([
+                value,
+                base64,
+                base64.replace(/=+$/, ""),
+                base64Url,
+                base64Url.replace(/=+$/, ""),
+            ]),
+        ];
+    }
+    const normalized = value.normalize("NFC");
     const formEncoded = new URLSearchParams({ value }).toString().slice("value=".length);
     let componentEncoded;
     try {
@@ -125,12 +145,31 @@ function sensitiveValueVariants(value) {
         // still safe to scrub, and URLSearchParams supplies its well-formed form.
         componentEncoded = value;
     }
-    return [...new Set([value, componentEncoded, formEncoded].map(normalizePercentEscapes))];
-}
-function allSensitiveValueVariants(sensitiveValues) {
+    const base64 = Buffer.from(value, "utf8").toString("base64");
+    const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+    const jsonEscaped = JSON.stringify(value).slice(1, -1);
+    return [
+        ...new Set([
+            value,
+            normalized,
+            componentEncoded,
+            formEncoded,
+            jsonEscaped,
+            base64,
+            base64.replace(/=+$/, ""),
+            base64Url,
+            base64Url.replace(/=+$/, ""),
+        ].map(normalizePercentEscapes)),
+    ];
+}
+export function allSensitiveValueVariants(sensitiveValues) {
     const variants = new Map();
     for (const sensitiveValue of sensitiveValues) {
         const requiresTokenBoundary = sensitiveValue.length < MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH;
+        // Long values are unlikely to be ordinary prose, so case folding is worth
+        // the extra over-redaction protection. Values of 4-7 characters remain
+        // case-sensitive because they commonly occur as words and identifiers.
+        const caseInsensitive = sensitiveValue.length >= 8;
         for (const value of sensitiveValueVariants(sensitiveValue)) {
             const existing = variants.get(value);
             variants.set(value, {
@@ -138,6 +177,7 @@ function allSensitiveValueVariants(sensitiveValues) {
                 requiresTokenBoundary: existing
                     ? existing.requiresTokenBoundary && requiresTokenBoundary
                     : requiresTokenBoundary,
+                caseInsensitive: existing ? existing.caseInsensitive || caseInsensitive : caseInsensitive,
             });
         }
     }
@@ -147,24 +187,24 @@ function isTokenCharacter(value) {
     return value !== undefined && /[\p{L}\p{N}]/u.test(value);
 }
 function replaceSensitiveVariant(text, variant) {
-    const pattern = variant.value.replace(/%([\da-f]{2})|[.*+?^${}()|[\]\\]/gi, (match, hex) => {
-        if (hex) {
-            return `%${[...String(hex)]
-                .map((character) => /[a-f]/i.test(character)
-                ? `[${character.toLowerCase()}${character.toUpperCase()}]`
-                : character)
-                .join("")}`;
-        }
-        return `\\${match}`;
-    });
-    return text.replace(new RegExp(pattern, "gu"), (match, offset, source) => {
-        const end = offset + match.length;
+    const normalized = normalizePercentEscapes(text);
+    const comparable = variant.caseInsensitive ? normalized.toLowerCase() : text;
+    const needle = variant.caseInsensitive ? variant.value.toLowerCase() : variant.value;
+    let cursor = 0;
+    let output = "";
+    for (let index = comparable.indexOf(needle); index !== -1; index = comparable.indexOf(needle, index + 1)) {
+        const end = index + needle.length;
         if (variant.requiresTokenBoundary &&
-            (isTokenCharacter(source[offset - 1]) || isTokenCharacter(source[end]))) {
-            return match;
-        }
-        return REDACTED_QUERY_VALUE;
-    });
+            (isTokenCharacter(comparable[index - 1]) || isTokenCharacter(comparable[end])))
+            continue;
+        // Unicode folding can change offsets; suppress the field instead of slicing a secret.
+        if (comparable.length !== text.length)
+            return REDACTED_QUERY_VALUE;
+        output += text.slice(cursor, index) + REDACTED_QUERY_VALUE;
+        cursor = end;
+        index = end - 1;
+    }
+    return cursor ? output + text.slice(cursor) : text;
 }
 /** Scrubs raw and URL-encoded secret values from diagnostic text. */
 export function redactSensitiveText(text, sensitiveValues, requestUrl, redactedUrl) {

package/dist/runtime/resolver-vendors/browser.js

@@ -111,7 +111,6 @@ async function runBoundedCleanup(cleanup, timeoutMs, challengeKind, operation, t
         onError(error) {
             return {
                 error_message: error instanceof Error ? error.message : String(error),
-                ...(error instanceof Error && error.stack ? { error_stack: error.stack } : {}),
             };
         },
     })

package/dist/runtime/resolver.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash } from "node:crypto";
 import { resolveProxyConfigAsync, } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
@@ -130,11 +131,11 @@ const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS = new Set([
     "custom",
 ]);
 function normalizedEnvValue(env, key) {
-    const value = env[key]?.trim();
+    const value = readDiagnosticEnv(key, env)?.trim();
     return value ? value : undefined;
 }
 function readPositiveIntegerEnv(env, name) {
-    const raw = env[name]?.trim();
+    const raw = readDiagnosticEnv(name, env)?.trim();
     if (!raw)
         return undefined;
     if (!/^[1-9]\d*$/.test(raw)) {

package/dist/runtime/stt.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError, ValidationError } from "../errors.js";
 import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
@@ -32,7 +33,7 @@ export function createUnsupportedSttClient(reason) {
     });
 }
 function normalizedEnvValue(env, key) {
-    const value = env[key]?.trim();
+    const value = readDiagnosticEnv(key, env)?.trim();
     return value ? value : undefined;
 }
 export function createSttClientFromEnv(config, env = process.env) {
@@ -53,7 +54,7 @@ export function createSttClientFromEnv(config, env = process.env) {
         });
     }
     const accountId = env.APIFUSE__CLOUDFLARE__ACCOUNT_ID?.trim();
-    const apiToken = env.APIFUSE__STT__CLOUDFLARE_API_TOKEN?.trim();
+    const apiToken = readDiagnosticEnv(APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, env)?.trim();
     if (!accountId || !apiToken) {
         return createUnsupportedSttClient(`STT backend ${backend} requires ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV}`);
     }

package/dist/runtime/trace.d.ts

@@ -1,4 +1,5 @@
 import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types.js";
+import { type DiagnosticRedactor } from "./diagnostic-redactor.js";
 import { type OTLPExportOptions } from "./otlp.js";
 export type SpanAttributeValue = TraceAttributeValue;
 export type Span = TraceSpan;
@@ -8,6 +9,8 @@ export interface TraceContext extends BaseTraceContext {
 export interface CreateTraceContextOptions {
     maxSpans?: number;
     onSpan?: (span: Span) => void;
+    /** Redacts diagnostic attribute values and errors before recording or calling onSpan. */
+    redact?: DiagnosticRedactor;
     exportOptions?: OTLPExportOptions;
     resourceAttributes?: Record<string, string>;
     /** W3C-compatible 32-character lowercase hexadecimal trace id used for export. */
@@ -34,5 +37,7 @@ export declare function updateTraceContextExportMetadata(trace: BaseTraceContext
 }): void;
 export declare function resolveTraceContextOptions(config?: TraceConfig): CreateTraceContextOptions;
 export declare function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null;
+/** Internal, read-only process counters; no reset can re-arm a warning. */
+export declare function getDroppedOTLPSpanCount(reason: string): number;
 export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;
 export {};

package/dist/runtime/trace.js

@@ -1,5 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { sanitizeSpanNameForOutput } from "../trace-sanitization.js";
+import { diagnosticStructuredRedactor, redactDiagnosticAttributeKey, copyDiagnosticAttributeTypes, redactedKeyAllocator, isRedactedKey, redactCriticalDiagnosticText, diagnosticAttributeRedactor, REDACTION_FAILED, redactDiagnosticText, } from "./diagnostic-redactor.js";
 import { exportSpansOTLP } from "./otlp.js";
+import { REDACTED_QUERY_VALUE } from "./request-options.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
 const TRACE_EXPORT_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/trace-export-metadata");
 function assertValidTraceId(traceId) {
@@ -32,23 +36,76 @@ export function resolveTraceContextOptions(config) {
         exportOptions: buildOTLPExportOptions(config),
     };
 }
-function normalizeAttributeValue(value) {
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-        return value;
+function normalizeAttributeValue(value, redact, retainBigints = false) {
+    if (typeof value === "number" || typeof value === "boolean") {
+        // Typed columns are contracts: unlike string tokens, number/boolean/bigint
+        // values only consult the registry at >=8 characters in string form.
+        const text = String(value);
+        if (text.length < 8)
+            return value;
+        const redacted = redactDiagnosticText(text, diagnosticStructuredRedactor(redact));
+        return redacted === text ? value : redacted;
+    }
+    if (typeof value === "bigint") {
+        // Bigints are not valid OTLP attribute primitives, so retain their prior
+        // string normalization while still checking their diagnostic form.
+        const text = String(value);
+        if (text.length < 8)
+            return retainBigints ? value : text;
+        const redacted = redactDiagnosticText(text, diagnosticStructuredRedactor(redact));
+        return retainBigints && redacted === text ? value : redacted;
     }
     if (value === null || value === undefined) {
         return undefined;
     }
-    return String(value);
+    return redactDiagnosticText(String(value), redact);
 }
-function normalizeAttributes(attributes) {
+function normalizeAttributes(attributes, redact, retainBigints = false) {
     if (!attributes) {
         return {};
     }
+    const nextKey = redactedKeyAllocator(Object.keys(attributes));
     const normalizedEntries = Object.entries(attributes)
-        .map(([key, value]) => [key, normalizeAttributeValue(value)])
+        .map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const normalizedKey = keyChanged ? nextKey() : key;
+        // Once a key changes, its original sensitivity classification is no
+        // longer available to later output sanitizers. Suppress the value here.
+        const normalizedValue = keyChanged
+            ? redactedKey === REDACTION_FAILED
+                ? REDACTION_FAILED
+                : REDACTED_QUERY_VALUE
+            : normalizeAttributeValue(value, diagnosticAttributeRedactor(key, redact), retainBigints);
+        return [normalizedKey, normalizedValue];
+    })
         .filter((entry) => entry[1] !== undefined);
-    return Object.fromEntries(normalizedEntries);
+    return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(normalizedEntries));
+}
+function prepareResourceAttributesForExport(attributes, redact, sanitize) {
+    if (!attributes)
+        return undefined;
+    if (sanitize) {
+        const sanitized = sanitize({ ...attributes });
+        if (!sanitized || typeof sanitized !== "object") {
+            throw new Error("resource attribute sanitizer returned no attributes");
+        }
+        return sanitized;
+    }
+    const nextKey = redactedKeyAllocator(Object.keys(attributes));
+    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+        return [
+            sanitizedKey,
+            keyChanged
+                ? redactedKey === REDACTION_FAILED
+                    ? REDACTION_FAILED
+                    : REDACTED_QUERY_VALUE
+                : sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact)),
+        ];
+    }));
 }
 function insertCompletedSpan(completed, entry, maxSpans) {
     const insertAt = completed.findIndex((existingEntry) => existingEntry.sequence > entry.sequence);
@@ -64,7 +121,10 @@ function insertCompletedSpan(completed, entry, maxSpans) {
 }
 /** Hands the hook a copy whose attributes are detached from the recorded span; a hook that returns nothing fails closed. */
 function prepareSpanForExport(span, sanitize) {
-    const copy = { ...span, attributes: { ...span.attributes } };
+    const copy = {
+        ...span,
+        attributes: copyDiagnosticAttributeTypes(span.attributes, { ...span.attributes }),
+    };
     if (!sanitize)
         return copy;
     const sanitized = sanitize(copy);
@@ -76,6 +136,24 @@ function prepareSpanForExport(span, sanitize) {
 export function getTraceRecorder(trace) {
     return trace[TRACE_RECORDER] ?? null;
 }
+const droppedOTLPSpans = new Map();
+/** Internal, read-only process counters; no reset can re-arm a warning. */
+export function getDroppedOTLPSpanCount(reason) {
+    return droppedOTLPSpans.get(reason) ?? 0;
+}
+function warnDroppedOTLPSpans(reason, count) {
+    const previous = getDroppedOTLPSpanCount(reason);
+    const total = previous + count;
+    droppedOTLPSpans.set(reason, total);
+    if (previous !== 0)
+        return;
+    try {
+        console.warn(`[apifuse] OTLP export skipped; reason=${reason}; dropped_spans=${total}`);
+    }
+    catch {
+        // Warning sinks are best-effort. The counter/latch survives a failed sink.
+    }
+}
 export function createTraceContext(options = {}) {
     if (options.traceId !== undefined)
         assertValidTraceId(options.traceId);
@@ -86,9 +164,11 @@ export function createTraceContext(options = {}) {
     // Export configuration (which can carry collector credentials) stays in this closure;
     // the context object handed to provider code never exposes it.
     const exportOptions = options.exportOptions;
-    const exportResourceAttributes = options.resourceAttributes
-        ? { ...options.resourceAttributes }
+    const resourceAttributeOptions = options.resourceAttributes;
+    const exportResourceAttributes = resourceAttributeOptions
+        ? { ...resourceAttributeOptions }
         : undefined;
+    const exportResourceAttributeSanitizer = resourceAttributeOptions?.[TRACE_RESOURCE_ATTRIBUTE_SANITIZER];
     // One trace id per context so every export batch of this request shares it and
     // two processes can never mint the same id.
     let exportTraceId = options.traceId ?? crypto.randomUUID().replace(/-/g, "");
@@ -109,46 +189,61 @@ export function createTraceContext(options = {}) {
                 return;
             // Sanitization runs off the request path; a faulty sanitizer drops the batch, never the request.
             let spans;
+            let resourceAttributes;
             try {
                 spans = pending.map((entry) => prepareSpanForExport(entry.span, options.sanitizeSpanForExport));
+                resourceAttributes = prepareResourceAttributesForExport(exportResourceAttributes, options.redact, exportResourceAttributeSanitizer);
             }
             catch {
-                console.warn("[apifuse] OTLP export skipped; span sanitization failed.");
+                try {
+                    console.warn("[apifuse] OTLP export skipped; span sanitization failed.");
+                }
+                catch {
+                    // A broken diagnostic sink must not escape this detached callback.
+                }
+                return;
+            }
+            // A matching trace ID cannot be replaced with non-hex text on the wire. Emit less.
+            if (redactCriticalDiagnosticText(exportTraceId, options.redact) !== exportTraceId) {
+                warnDroppedOTLPSpans("unverifiable_trace_id", pending.length);
                 return;
             }
-            void exportSpansOTLP(spans, exportOptions, exportResourceAttributes, exportTraceId);
+            void exportSpansOTLP(spans, exportOptions, resourceAttributes, exportTraceId);
         });
     };
     const recorder = {
         async runSpan(name, fn, spanOptions = {}) {
             const pendingSpan = {
                 id: crypto.randomUUID(),
-                name,
+                name: redactCriticalDiagnosticText(name, options.redact),
                 startedAt: Date.now(),
                 parentId: activeSpanStorage.getStore()?.id,
                 sequence: sequence++,
-                attributes: normalizeAttributes(spanOptions.attributes),
+                attributes: normalizeAttributes(spanOptions.attributes, options.redact, true),
             };
             const finalize = (status, extraAttributes, error) => {
                 const endedAt = Date.now();
                 const duration = endedAt - pendingSpan.startedAt;
                 const attributes = {
                     ...pendingSpan.attributes,
-                    ...normalizeAttributes(extraAttributes),
+                    ...extraAttributes,
                 };
                 if (attributes.duration_ms === undefined) {
                     attributes.duration_ms = duration;
                 }
                 const span = {
-                    id: pendingSpan.id,
-                    name: pendingSpan.name,
+                    id: redactCriticalDiagnosticText(pendingSpan.id, options.redact),
+                    // Recheck at recording: harvest and live env reads may follow span start.
+                    name: redactCriticalDiagnosticText(pendingSpan.name, options.redact),
                     startedAt: pendingSpan.startedAt,
                     endedAt,
                     duration_ms: duration,
                     status,
-                    attributes,
-                    ...(error ? { error } : {}),
-                    ...(pendingSpan.parentId ? { parentId: pendingSpan.parentId } : {}),
+                    attributes: normalizeAttributes(attributes, options.redact),
+                    ...(error ? { error: redactDiagnosticText(error, options.redact) } : {}),
+                    ...(pendingSpan.parentId
+                        ? { parentId: redactCriticalDiagnosticText(pendingSpan.parentId, options.redact) }
+                        : {}),
                 };
                 insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span, exported: false }, maxSpans);
                 options.onSpan?.(span);

package/dist/schema.d.ts

@@ -22,6 +22,8 @@ export type SensitiveFieldKind = "api_key" | "authorization" | "cookie" | "crede
 export interface SensitiveFieldOptions {
     /**
      * Mark this schema as sensitive. Defaults to true for the helper presets.
+     * An explicit `false` emits `x-apifuse-sensitive: false` (reviewed public
+     * data, never redacted) and drops any sensitivity kind.
      */
     sensitive?: boolean;
     /**
@@ -48,6 +50,15 @@ declare module "zod" {
 }
 export declare function field<TSchema extends ZodType>(schema: TSchema, options?: SensitiveFieldOptions): TSchema;
 export declare function sensitive<TSchema extends ZodType>(schema: TSchema, kind?: SensitiveFieldKind): TSchema;
+/**
+ * Declare a field as reviewed public data (business, facility, product, or
+ * place names and contacts) so a key-based privacy classifier hit counts as
+ * declared instead of undeclared. Emits `x-apifuse-sensitive: false` on the
+ * JSON Schema leaf; nothing is redacted. Use `sensitive()` for anything that
+ * identifies a person. Apply it to the leaf, before `.optional()` or
+ * `.nullable()`; wrapping a `sensitive()` declaration throws at definition time.
+ */
+export declare function publicField<TSchema extends ZodType>(schema: TSchema): TSchema;
 export declare const fields: {
     readonly apiKey: (options?: {
         description?: string;

package/dist/schema.js

@@ -113,15 +113,41 @@ export function field(schema, options = {}) {
         ? schema.describe(options.description)
         : schema;
     const metadata = described.meta() ?? {};
+    const isSensitive = options.sensitive ?? true;
+    // A public declaration only rewrites the meta of the node it receives;
+    // z.toJSONSchema folds that over the inner leaf, so `false` on a wrapper
+    // around a sensitive() leaf would publish `false` next to the leaf's kind
+    // while collectSensitivePaths() still redacts. Refuse the contradiction.
+    if (!isSensitive && wrapsSensitiveDeclaration(described)) {
+        throw new TypeError("publicField()/field({ sensitive: false }) wraps a sensitive() declaration; apply it to the leaf, before .optional(), .nullable(), .default(), .pipe(), z.lazy() or similar wrappers.");
+    }
+    // Zod merges meta with the parent chain, so an inherited kind can only be
+    // cleared by writing undefined over it (dropped from JSON Schema output).
+    const kind = isSensitive
+        ? (options.kind ?? Reflect.get(metadata, APIFUSE_SENSITIVE_KIND_META_KEY))
+        : undefined;
     return described.meta({
         ...metadata,
-        ...((options.sensitive ?? true) ? { [APIFUSE_SENSITIVE_META_KEY]: true } : {}),
-        ...(options.kind ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind } : {}),
+        [APIFUSE_SENSITIVE_META_KEY]: isSensitive,
+        ...(kind !== undefined || APIFUSE_SENSITIVE_KIND_META_KEY in metadata
+            ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: kind }
+            : {}),
     });
 }
 export function sensitive(schema, kind) {
     return field(schema, { sensitive: true, kind });
 }
+/**
+ * Declare a field as reviewed public data (business, facility, product, or
+ * place names and contacts) so a key-based privacy classifier hit counts as
+ * declared instead of undeclared. Emits `x-apifuse-sensitive: false` on the
+ * JSON Schema leaf; nothing is redacted. Use `sensitive()` for anything that
+ * identifies a person. Apply it to the leaf, before `.optional()` or
+ * `.nullable()`; wrapping a `sensitive()` declaration throws at definition time.
+ */
+export function publicField(schema) {
+    return field(schema, { sensitive: false });
+}
 function sensitiveString(kind, description, options = {}) {
     const schema = options.minLength === undefined ? z.string() : z.string().min(options.minLength);
     return field(schema, {
@@ -238,6 +264,34 @@ function readZodMetadata(schema) {
     const metadata = maybeMeta.call(schema);
     return metadata && typeof metadata === "object" ? metadata : undefined;
 }
+// Same-path wrappers (optional, nullable, default, catch, readonly, pipe,
+// lazy, ...) share the JSON Schema leaf with the schema they wrap.
+function wrapsSensitiveDeclaration(schema, seen = new Set()) {
+    const def = readZodDef(schema);
+    if (!def || seen.has(schema))
+        return false;
+    seen.add(schema);
+    return sameLeafChildren(def).some((child) => isSensitiveSchema(child) || wrapsSensitiveDeclaration(child, seen));
+}
+function sameLeafChildren(def) {
+    switch (Reflect.get(def, "type")) {
+        case "pipe":
+            return [Reflect.get(def, "in"), Reflect.get(def, "out")];
+        case "lazy": {
+            // A forward-reference getter can throw before its target is
+            // initialised; treat that as no declaration rather than failing.
+            const getter = Reflect.get(def, "getter");
+            try {
+                return typeof getter === "function" ? [getter()] : [];
+            }
+            catch {
+                return [];
+            }
+        }
+        default:
+            return [Reflect.get(def, "innerType")];
+    }
+}
 function readZodDef(schema) {
     if (!schema || typeof schema !== "object")
         return undefined;