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

package/dist/server/trace-output.d.ts

@@ -1,6 +1,7 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
 import { type CreateTraceContextOptions } from "../runtime/trace.js";
 import type { TraceConfig } from "../types.js";
 type EnvLike = Record<string, string | undefined>;
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike): CreateTraceContextOptions;
+export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike, redact?: DiagnosticRedactor): CreateTraceContextOptions;
 export {};

package/dist/server/trace-output.js

@@ -1,7 +1,9 @@
 import { isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE } from "../fixture-sanitization.js";
+import { redactedKeyAllocator, isRedactedKey, REDACTION_FAILED, redactDiagnosticText, } from "../runtime/diagnostic-redactor.js";
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, resolveOTLPExportOptions, resolveOTLPResourceAttributes, } from "../runtime/otlp.js";
 import { resolveTraceContextOptions, } from "../runtime/trace.js";
 import { sanitizeSpanForOutput, sanitizeSpanNameForOutput, sanitizeTraceAttributes, } from "../trace-sanitization.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
 // Warn once per environment object: process.env in production, each injected env in tests.
 const warnedEnvironments = new WeakSet();
 const warnedResourceEnvironments = new WeakSet();
@@ -36,25 +38,48 @@ function resolveServerOTLPExportOptions(config, env) {
  * environment are identifiers rather than request data: their values are kept, with control
  * characters neutralized, length bounded, and secret-named keys redacted.
  */
-function resolveExportResourceAttributes(requestAttributes, env) {
+function resolveExportResourceAttributes(requestAttributes, env, redact) {
     const resolution = resolveOTLPResourceAttributes({}, env);
     warnDiscardedResourceAttributes(env, resolution);
-    const operatorAttributes = Object.fromEntries(Object.entries(resolution.attributes).map(([key, value]) => [
-        sanitizeSpanNameForOutput(key),
-        isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeSpanNameForOutput(value),
-    ]));
-    const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(requestAttributes)).map(([key, value]) => [
-        key,
-        String(value),
-    ]));
-    return { ...operatorAttributes, ...sanitizedRequestAttributes };
+    const operatorAttributes = resolution.attributes;
+    const requestKeys = new Set(Object.keys(requestAttributes));
+    return {
+        // Keep the raw snapshot private until export. A credential registered after
+        // trace creation must be matched before any key or value is bounded.
+        attributes: { ...operatorAttributes, ...requestAttributes },
+        sanitize(attributes) {
+            const nextKey = redactedKeyAllocator(Object.keys(attributes));
+            const sanitizedOperatorAttributes = {};
+            const rawRequestAttributes = {};
+            for (const [key, value] of Object.entries(attributes)) {
+                const unchangedOperatorValue = !requestKeys.has(key) && operatorAttributes[key] === value;
+                if (unchangedOperatorValue) {
+                    const redactedKey = isRedactedKey(key) ? key : redactDiagnosticText(key, redact);
+                    const keyChanged = redactedKey !== key;
+                    const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+                    sanitizedOperatorAttributes[sanitizedKey] = keyChanged
+                        ? redactedKey === REDACTION_FAILED
+                            ? REDACTION_FAILED
+                            : REDACTED_FIXTURE_VALUE
+                        : isSensitiveFixtureKey(key)
+                            ? REDACTED_FIXTURE_VALUE
+                            : sanitizeSpanNameForOutput(value, redact);
+                }
+                else {
+                    rawRequestAttributes[key] = value;
+                }
+            }
+            const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(rawRequestAttributes, redact, Object.keys(sanitizedOperatorAttributes))).map(([key, value]) => [key, String(value)]));
+            return { ...sanitizedOperatorAttributes, ...sanitizedRequestAttributes };
+        },
+    };
 }
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env) {
+export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env, redact) {
     const resolved = resolveTraceContextOptions(config);
     const outputEnabled = config.enabled !== false && config.exporter !== "none";
     const consoleHook = outputEnabled && (config.exporter === "console" || config.exporter === "json")
-        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes)))
+        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes, redact)))
         : undefined;
     const onSpan = consoleHook && resolved.onSpan
         ? (span) => {
@@ -65,14 +90,21 @@ export function resolveServerTraceContextOptions(config, resourceAttributes, env
     const exportOptions = outputEnabled && config.exporter === "otlp"
         ? resolveServerOTLPExportOptions(config, env)
         : undefined;
+    const exportResources = exportOptions
+        ? resolveExportResourceAttributes(resourceAttributes, env, redact)
+        : undefined;
+    if (exportResources) {
+        Object.defineProperty(exportResources.attributes, TRACE_RESOURCE_ATTRIBUTE_SANITIZER, { value: exportResources.sanitize });
+    }
     return {
         maxSpans: resolved.maxSpans,
         onSpan,
+        ...(redact ? { redact } : {}),
         ...(exportOptions
             ? {
                 exportOptions,
-                resourceAttributes: resolveExportResourceAttributes(resourceAttributes, env),
-                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span),
+                resourceAttributes: exportResources?.attributes,
+                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span, undefined, redact),
             }
             : {}),
     };

package/dist/trace-sanitization.d.ts

@@ -1,5 +1,6 @@
+import { type DiagnosticRedactor } from "./runtime/diagnostic-redactor.js";
 import type { TraceSpan } from "./types.js";
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export declare function sanitizeSpanNameForOutput(value: string): string;
-export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>): Record<string, string | number | boolean>;
-export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>): TraceSpan;
+export declare function sanitizeSpanNameForOutput(value: string, redact?: DiagnosticRedactor): string;
+export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>, redact?: DiagnosticRedactor, reservedKeys?: Iterable<string>): Record<string, string | number | boolean>;
+export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>, redact?: DiagnosticRedactor): TraceSpan;

package/dist/trace-sanitization.js

@@ -1,45 +1,68 @@
 import { encodeDiagnosticControls, isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "./fixture-sanitization.js";
+import { diagnosticStructuredRedactor, redactDiagnosticAttributeKey, copyDiagnosticAttributeTypes, isDiagnosticBigintAttribute, redactedKeyAllocator, isRedactedKey, redactCriticalDiagnosticText, diagnosticAttributeRedactor, REDACTION_FAILED, redactDiagnosticText, } from "./runtime/diagnostic-redactor.js";
 const MAX_TRACE_TEXT_LENGTH = 300;
-function sanitizeTraceText(value) {
-    const encoded = sanitizeDiagnosticText(value);
+function sanitizeTraceText(value, redact) {
+    const encoded = sanitizeDiagnosticText(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export function sanitizeSpanNameForOutput(value) {
-    const encoded = encodeDiagnosticControls(value);
+export function sanitizeSpanNameForOutput(value, redact) {
+    const encoded = encodeDiagnosticControls(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
-export function sanitizeTraceAttributes(attributes) {
-    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
-        sanitizeTraceText(key),
-        isSensitiveFixtureKey(key)
-            ? REDACTED_FIXTURE_VALUE
-            : typeof value === "string"
-                ? sanitizeTraceText(value)
-                : typeof value === "number" || typeof value === "boolean"
-                    ? value
-                    : sanitizeTraceText(String(value)),
-    ]));
+export function sanitizeTraceAttributes(attributes, redact, reservedKeys = []) {
+    const nextKey = redactedKeyAllocator([...Object.keys(attributes), ...reservedKeys]);
+    return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const sanitizedKey = keyChanged ? nextKey() : sanitizeTraceText(key);
+        const valueRedactor = typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+            ? diagnosticStructuredRedactor(redact)
+            : diagnosticAttributeRedactor(key, redact);
+        const sanitizedValue = keyChanged
+            ? redactedKey === REDACTION_FAILED
+                ? REDACTION_FAILED
+                : REDACTED_FIXTURE_VALUE
+            : isSensitiveFixtureKey(key)
+                ? REDACTED_FIXTURE_VALUE
+                : typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+                    ? String(value).length < 8
+                        ? String(value)
+                        : sanitizeTraceText(String(value), valueRedactor)
+                    : typeof value === "string"
+                        ? sanitizeTraceText(value, valueRedactor)
+                        : typeof value === "number" || typeof value === "boolean"
+                            ? (() => {
+                                if (String(value).length < 8)
+                                    return value;
+                                const redacted = redactDiagnosticText(String(value), diagnosticStructuredRedactor(valueRedactor));
+                                return redacted === String(value) ? value : sanitizeTraceText(redacted);
+                            })()
+                            : sanitizeTraceText(String(value), valueRedactor);
+        return [sanitizedKey, sanitizedValue];
+    })));
 }
-export function sanitizeSpanForOutput(span, additionalAttributes) {
+export function sanitizeSpanForOutput(span, additionalAttributes, redact) {
     // Keep this schema explicit so future fields are not silently added to a
     // process output path before their trust boundary has been reviewed.
     return {
-        id: span.id,
-        name: sanitizeSpanNameForOutput(span.name),
+        id: redactCriticalDiagnosticText(span.id, redact),
+        name: sanitizeSpanNameForOutput(redactCriticalDiagnosticText(span.name, redact)),
         startedAt: span.startedAt,
         endedAt: span.endedAt,
         duration_ms: span.duration_ms,
         status: span.status,
-        attributes: sanitizeTraceAttributes({
+        attributes: sanitizeTraceAttributes(copyDiagnosticAttributeTypes(span.attributes, {
             ...span.attributes,
             ...(additionalAttributes ?? {}),
-        }),
-        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error) } : {}),
-        ...(span.parentId !== undefined ? { parentId: span.parentId } : {}),
+        }), redact),
+        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error, redact) } : {}),
+        ...(span.parentId !== undefined
+            ? { parentId: redactCriticalDiagnosticText(span.parentId, redact) }
+            : {}),
     };
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.59",
+	"version": "2.2.0-beta.60",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -110,6 +110,7 @@
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
+		"bench:redaction": "bun scripts/benchmark-request-redaction.ts",
 		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
 		"api:update": "bun run build && bun scripts/api-reports.ts update",
 		"api:check": "bun run build && bun scripts/api-reports.ts check",

package/src/config/loader.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "../runtime/diagnostic-env.js";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -256,8 +257,8 @@ const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 
 function redisUrlFromEnv(): string | undefined {
 	return (
-		process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -268,9 +269,9 @@ export function providerCacheRedisUrlFromEnv(): string | undefined {
 
 export function providerStateRedisUrlFromEnv(): string | undefined {
 	return (
-		process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
-		process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_STATE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -693,12 +694,12 @@ export async function resolveWithVendor(
 		const startedAt = Date.now();
 		const username = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: context.credentials[NODEMAVEN_USERNAME_ENV]
 		)?.trim();
 		const password = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_PASSWORD_ENV]
+				? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 				: context.credentials[NODEMAVEN_PASSWORD_ENV]
 		)?.trim();
 		const filter =
@@ -749,7 +750,7 @@ export async function resolveWithVendor(
 	// smartproxy allocation-style vendor.
 	const appKey = (
 		context.credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: context.credentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) {
@@ -838,18 +839,18 @@ function vendorHasCredentials(
 	if (vendor === "nodemaven") {
 		return Boolean(
 			(credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: credentials[NODEMAVEN_USERNAME_ENV]
 			)?.trim() &&
 				(credentials === undefined
-					? process.env[NODEMAVEN_PASSWORD_ENV]
+					? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 					: credentials[NODEMAVEN_PASSWORD_ENV]
 				)?.trim(),
 		);
 	}
 	return Boolean(
 		(credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: credentials[SMARTPROXY_APP_KEY_ENV]
 		)?.trim(),
 	);
@@ -1757,7 +1758,7 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
 	const appKey = (
 		options.engineCredentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: options.engineCredentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) return undefined;

package/src/engine.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./runtime/diagnostic-env.js";
 import { ProviderError } from "./errors.js";
 import {
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
@@ -160,7 +161,7 @@ export function readEngineProxyCredentials(
 ): Readonly<Record<string, string>> {
 	return Object.fromEntries(
 		ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
-			const value = environment[name]?.trim();
+			const value = readDiagnosticEnv(name, environment)?.trim();
 			return value ? [[name, value] as const] : [];
 		}),
 	);
@@ -174,7 +175,7 @@ export function createProviderEnvironment(
 	return Object.fromEntries(
 		declaredNames.flatMap((name) => {
 			if (isEngineOwnedEnvName(name)) return [];
-			const value = environment[name];
+			const value = readDiagnosticEnv(name, environment);
 			return value === undefined ? [] : [[name, value] as const];
 		}),
 	);

package/src/index.ts

@@ -275,6 +275,7 @@ export {
 	type Span,
 	type TraceContext,
 } from "./runtime/trace.js";
+export type { DiagnosticRedactor } from "./runtime/diagnostic-redactor.js";
 export {
 	APIFUSE_CONTENT_PROVENANCE_META_KEY,
 	APIFUSE_CONTENT_TRUST_META_KEY,
@@ -287,6 +288,7 @@ export {
 	field,
 	fields,
 	isSensitiveSchema,
+	publicField,
 	redactPayload,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,

package/src/lint.ts

@@ -550,18 +550,29 @@ function uniqueFields(fields: string[]): string[] {
 	return Array.from(new Set(fields));
 }
 
-function isSensitiveSchema(schema: unknown): boolean {
-	if (!schema || typeof schema !== "object" || !("meta" in schema)) {
-		return false;
+function readSensitivityDeclaration(
+	schema: unknown,
+	seen = new Set<unknown>(),
+): boolean | undefined {
+	// Declarations sit on the leaf; same-path wrappers such as .optional(),
+	// .nullable(), .pipe() or z.lazy() carry no metadata of their own, so look
+	// through them.
+	if (!isSchema(schema) || seen.has(schema)) return undefined;
+	seen.add(schema);
+	const value = Reflect.get(getSchemaMetadata(schema), APIFUSE_SENSITIVE_META_KEY);
+	if (typeof value === "boolean") return value;
+	const def = getSchemaDef(schema);
+	const children =
+		def.type === "pipe"
+			? [def.in, def.out]
+			: def.type === "lazy" && typeof def.getter === "function"
+				? [def.getter()]
+				: [def.innerType];
+	for (const child of children) {
+		const declaration = readSensitivityDeclaration(child, seen);
+		if (declaration !== undefined) return declaration;
 	}
-	const meta = schema.meta;
-	if (typeof meta !== "function") return false;
-	const metadata = meta.call(schema);
-	return (
-		!!metadata &&
-		typeof metadata === "object" &&
-		Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true
-	);
+	return undefined;
 }
 
 function getSchemaMetadata(schema: SchemaLike): Record<string, unknown> {
@@ -591,9 +602,24 @@ const SENSITIVE_FIELD_NAMES = new Set([
 	"paymenturl",
 ]);
 
+// Only phone-shaped keys can hold reviewed public data (facility phones); the
+// rest are credentials, which a public declaration must not launder.
+const PUBLIC_DECLARABLE_FIELD_NAMES = new Set(["phone", "phonenumber"]);
+
+function normalizeFieldName(name: string): string {
+	return name.toLowerCase().replace(/[-_\s]/g, "");
+}
+
 function isSensitiveFieldName(name: string): boolean {
-	const normalized = name.toLowerCase().replace(/[-_\s]/g, "");
-	return SENSITIVE_FIELD_NAMES.has(normalized);
+	return SENSITIVE_FIELD_NAMES.has(normalizeFieldName(name));
+}
+
+function isDeclaredSensitiveField(key: string, schema: unknown): boolean {
+	const declaration = readSensitivityDeclaration(schema);
+	return (
+		declaration === true ||
+		(declaration === false && PUBLIC_DECLARABLE_FIELD_NAMES.has(normalizeFieldName(key)))
+	);
 }
 
 function collectUnmarkedSensitiveFields(
@@ -608,7 +634,7 @@ function collectUnmarkedSensitiveFields(
 	const out: string[] = [];
 	for (const [key, child] of Object.entries(getObjectShape(schema))) {
 		const childPath = basePath ? `${basePath}.${key}` : key;
-		if (isSensitiveFieldName(key) && !isSensitiveSchema(child)) {
+		if (isSensitiveFieldName(key) && !isDeclaredSensitiveField(key, child)) {
 			out.push(childPath);
 		}
 		out.push(...collectUnmarkedSensitiveFields(child, childPath, seen));
@@ -1401,7 +1427,7 @@ export function lintOperation(op: {
 			rule: "sensitive-field-unmarked",
 			level: "warn",
 			field,
-			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*() or sensitive(...); publicField(...) is accepted only for reviewed public phone-shaped fields.`,
 		});
 	}
 
@@ -1410,7 +1436,7 @@ export function lintOperation(op: {
 			rule: "sensitive-field-unmarked",
 			level: "warn",
 			field,
-			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*() or sensitive(...); publicField(...) is accepted only for reviewed public phone-shaped fields.`,
 		});
 	}
 

package/src/provider.ts

@@ -179,6 +179,7 @@ export {
 	field,
 	fields,
 	isSensitiveSchema,
+	publicField,
 	redactPayload,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,

package/src/runtime/browser.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createRequire } from "node:module";
 import type { CDPSession, Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
 
@@ -495,7 +496,7 @@ type SupportedBrowserClient = {
 };
 
 function getDefaultCdpPoolUrl(env = process.env): string | undefined {
-	return env.APIFUSE__CDP_POOL__URL;
+	return readDiagnosticEnv("APIFUSE__CDP_POOL__URL", env);
 }
 
 async function importOptionalModule<T extends object>(moduleName: string): Promise<T> {

package/src/runtime/cache.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, createHmac } from "node:crypto";
 
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
@@ -362,7 +363,7 @@ async function withRedisFallback<T>(operation: () => Promise<T>): Promise<T | un
 
 export function createProviderCache(options: ProviderCacheOptions): ProviderCache {
 	const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
-	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const configuredPepper = readDiagnosticEnv(APIFUSE__CACHE__KEY_PEPPER_ENV);
 	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const backend = getSharedBackend(redisUrl);
 	const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
@@ -599,7 +600,7 @@ export function isProviderCacheBypassed(cache: ProviderCache): boolean {
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
-	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const configuredPepper = readDiagnosticEnv(APIFUSE__CACHE__KEY_PEPPER_ENV);
 	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const events: ProviderCacheLookupMeta[] = [];
 	const secretScopedKeys = new Set<string>();

package/src/runtime/diagnostic-env-values.ts

@@ -0,0 +1,56 @@
+export function resolvedStringVariants(value: string | undefined): string[] {
+	if (value === undefined) return [];
+	return [...new Set([value, value.trim()])].filter((candidate) => candidate.length > 0);
+}
+
+function decodedComponent(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
+export function urlCredentialComponents(
+	value: string,
+	options: { includePathAndQuery: boolean },
+): string[] {
+	let url: URL;
+	try {
+		url = new URL(value.trim());
+	} catch {
+		return [];
+	}
+	const username = decodedComponent(url.username);
+	const password = decodedComponent(url.password);
+	const components = [username, password, username && password ? `${username}:${password}` : ""];
+	if (options.includePathAndQuery) {
+		for (const segment of url.pathname.split("/")) {
+			if (segment) components.push(decodedComponent(segment));
+		}
+		for (const [key, entryValue] of url.searchParams) {
+			if (key) components.push(key);
+			if (entryValue) {
+				components.push(entryValue, `${key}=${entryValue}`);
+			}
+		}
+	}
+	return [...new Set(components.flatMap((component) => resolvedStringVariants(component)))];
+}
+
+export function otlpHeaderCredentialValues(value: string): string[] {
+	const variants = resolvedStringVariants(value);
+	for (const member of value.split(",")) {
+		const separator = member.indexOf("=");
+		if (separator <= 0) continue;
+		const headerValue = decodedComponent(member.slice(separator + 1).trim());
+		variants.push(...resolvedStringVariants(headerValue));
+		const headerName = decodedComponent(member.slice(0, separator).trim()).toLowerCase();
+		if (headerName === "authorization" || headerName === "proxy-authorization") {
+			// A transport may echo just the credential without its HTTP auth scheme.
+			const credential = /^(?:Bearer|Basic)\s+(.+)$/i.exec(headerValue)?.[1];
+			if (credential) variants.push(...resolvedStringVariants(credential));
+		}
+	}
+	return [...new Set(variants)];
+}

package/src/runtime/diagnostic-env.ts

@@ -0,0 +1,55 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import {
+	resolvedStringVariants,
+	urlCredentialComponents,
+	otlpHeaderCredentialValues,
+} from "./diagnostic-env-values.js";
+import {
+	type CompiledDiagnosticSensitiveValues,
+	registerProcessDiagnosticValues,
+	suppressProcessDiagnosticValues,
+	withAppDiagnosticFallback,
+} from "./diagnostic-redactor.js";
+
+type EnvObserver = (name: string, value: string) => void;
+export interface DiagnosticEnvScope {
+	observe: EnvObserver;
+	finished: boolean;
+	staticValues?: CompiledDiagnosticSensitiveValues;
+}
+const observers = new AsyncLocalStorage<DiagnosticEnvScope>();
+
+/** Resolve and register atomically, before any consumer can use a live env credential. */
+export function readDiagnosticEnv(
+	name: string,
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): string | undefined {
+	const value = env[name];
+	if (value !== undefined) {
+		const scope = observers.getStore();
+		if (scope && !scope.finished) scope.observe(name, value);
+		else {
+			// ALS survives the response. Finished requests register into the app's
+			// inherited fallback lifetime, never a dead request's private inventory.
+			if (Buffer.byteLength(value) > 64 * 1024) suppressProcessDiagnosticValues();
+			else
+				registerProcessDiagnosticValues([
+					...resolvedStringVariants(value),
+					...urlCredentialComponents(value, {
+						includePathAndQuery: name === "APIFUSE__CDP_POOL__URL",
+					}),
+					...(name === "OTEL_EXPORTER_OTLP_HEADERS" || name === "OTEL_EXPORTER_OTLP_TRACES_HEADERS"
+						? otlpHeaderCredentialValues(value)
+						: []),
+				]);
+		}
+	}
+	return value;
+}
+
+export function withDiagnosticEnv<T>(observer: EnvObserver | DiagnosticEnvScope, fn: () => T): T {
+	const scope = typeof observer === "function" ? { observe: observer, finished: false } : observer;
+	const run = () => observers.run(scope, fn);
+	return scope.staticValues ? withAppDiagnosticFallback(scope.staticValues, run) : run();
+}