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

package/src/runtime/state.ts

@@ -75,9 +75,12 @@ if not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
 end
 
 if current_decoded and type(current_decoded.createdAt) == "string" then
-	local next_decoded = cjson.decode(envelope)
-	next_decoded.createdAt = current_decoded.createdAt
-	envelope = cjson.encode(next_decoded)
+	-- Preserve the original createdAt by patching the encoded envelope in place.
+	-- The envelope puts its metadata before "value", so the first match is the
+	-- envelope's own key, never a provider value; re-encoding with cjson would
+	-- silently turn [] inside the value into {}.
+	local preserved = string.gsub(current_decoded.createdAt, "%%", "%%%%")
+	envelope = (string.gsub(envelope, '"createdAt":"[^"]*"', '"createdAt":"' .. preserved .. '"', 1))
 end
 redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
 redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
@@ -267,7 +270,11 @@ function redisEnvelope(
 	expiresAt: string,
 ): RedisStateEnvelope {
 	const updatedAt = new Date().toISOString();
-	return { value, version, expiresAt, createdAt, updatedAt };
+	// Metadata precedes `value` on purpose: the compare-and-set Lua script patches
+	// `createdAt` in the encoded string (first occurrence) instead of decoding and
+	// re-encoding with cjson, which would turn empty arrays inside `value` into
+	// objects. Keep the key order stable.
+	return { version, expiresAt, createdAt, updatedAt, value };
 }
 
 class RedisProviderStateNamespace implements ProviderStateNamespace {
@@ -604,7 +611,10 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 	// biome-ignore lint/suspicious/noExplicitAny: in-memory state stores heterogeneous generic values by key.
 	readonly values = new Map<string, StateValue<any>>();
 
-	constructor(private readonly options: StateNamespaceOptions) {}
+	constructor(
+		private readonly options: StateNamespaceOptions,
+		private readonly now: () => number = Date.now,
+	) {}
 
 	private enforceValueSize(value: unknown): void {
 		const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -631,7 +641,7 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 		}
 	}
 
-	private pruneExpired(nowMs = Date.now()): void {
+	private pruneExpired(nowMs = this.now()): void {
 		for (const [key, row] of this.values.entries()) {
 			if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
 				this.values.delete(key);
@@ -655,9 +665,12 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 	async set<T>(key: string, value: T, options?: StateWriteOptions): Promise<StateValue<T>> {
 		this.pruneExpired();
 		this.enforceWritePolicy(key, value, options?.ttl);
-		const now = new Date().toISOString();
+		const now = new Date(this.now()).toISOString();
 		const current = this.values.get(key);
-		const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
+		const expiresAt = resolveMemoryStateExpiresAt(
+			options?.ttl ?? this.options.defaultTtl,
+			this.now(),
+		);
 		const row = {
 			key,
 			value,
@@ -692,13 +705,14 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 			return { ok: false, current: current ?? null };
 		}
 		this.enforceWritePolicy(key, value, options?.ttl);
-		const now = new Date().toISOString();
+		const now = new Date(this.now()).toISOString();
 		const stored = {
 			key,
 			value,
 			version: expectedVersion + 1,
 			expiresAt: resolveMemoryStateExpiresAt(
 				options?.ttl ?? this.options.defaultTtl,
+				this.now(),
 			),
 			createdAt: current?.createdAt ?? now,
 			updatedAt: now,
@@ -725,11 +739,16 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 
 type MemoryProviderStateBackend = {
 	readonly namespaces: Map<string, MemoryProviderStateNamespace>;
+	/** Clock used for expiry; tests inject a fake clock so ttl behaviour matches production. */
+	readonly now: () => number;
 };
 
 class MemoryProviderRuntimeState implements ProviderRuntimeState {
 	constructor(
-		private readonly backend: MemoryProviderStateBackend = { namespaces: new Map() },
+		private readonly backend: MemoryProviderStateBackend = {
+			namespaces: new Map(),
+			now: Date.now,
+		},
 		private readonly scopeDiscriminator = MISSING_CONNECTION_SCOPE_DISCRIMINATOR,
 	) {}
 
@@ -746,15 +765,18 @@ class MemoryProviderRuntimeState implements ProviderRuntimeState {
 		const namespaceIdentity = `${scopeDiscriminator}\0${name}`;
 		const existing = this.backend.namespaces.get(namespaceIdentity);
 		if (existing) return existing;
-		const created = new MemoryProviderStateNamespace(options);
+		const created = new MemoryProviderStateNamespace(options, this.backend.now);
 		this.backend.namespaces.set(namespaceIdentity, created);
 		return created;
 	}
 }
 
-function resolveMemoryStateExpiresAt(ttl: StateWriteOptions["ttl"]): string {
+function resolveMemoryStateExpiresAt(
+	ttl: StateWriteOptions["ttl"],
+	nowMs = Date.now(),
+): string {
 	const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
-	if (!match) return new Date(Date.now() + 3_600_000).toISOString();
+	if (!match) return new Date(nowMs + 3_600_000).toISOString();
 	const amount = Number(match[1]);
 	const unit = match[2];
 	const multiplier =
@@ -767,7 +789,7 @@ function resolveMemoryStateExpiresAt(ttl: StateWriteOptions["ttl"]): string {
 					: unit === "h"
 						? 3_600_000
 						: 86_400_000;
-	return new Date(Date.now() + amount * multiplier).toISOString();
+	return new Date(nowMs + amount * multiplier).toISOString();
 }
 
 export function createRedisProviderRuntimeState(
@@ -792,8 +814,14 @@ export function createProviderRuntimeStateFromEnv(
 	return createUnsupportedProviderRuntimeState();
 }
 
-export function createMemoryProviderRuntimeState(): ProviderRuntimeState {
-	return new MemoryProviderRuntimeState();
+export function createMemoryProviderRuntimeState(options?: {
+	/** Clock for expiry and timestamps; defaults to `Date.now`. */
+	readonly now?: () => number;
+}): ProviderRuntimeState {
+	return new MemoryProviderRuntimeState({
+		namespaces: new Map(),
+		now: options?.now ?? Date.now,
+	});
 }
 
 export function createUnsupportedProviderRuntimeState(): ProviderRuntimeState {

package/src/runtime/stt.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError, ValidationError } from "../errors.js";
 import type {
 	Bcp47Locale,
@@ -69,7 +70,7 @@ export function createUnsupportedSttClient(reason?: string): SttContext {
 }
 
 function normalizedEnvValue(env: EnvLike, key: string): string | undefined {
-	const value = env[key]?.trim();
+	const value = readDiagnosticEnv(key, env)?.trim();
 	return value ? value : undefined;
 }
 
@@ -99,7 +100,7 @@ export function createSttClientFromEnv(
 	}
 
 	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/src/runtime/trace.ts

@@ -1,12 +1,25 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-
+import { sanitizeSpanNameForOutput } from "../trace-sanitization.js";
 import type {
 	TraceContext as BaseTraceContext,
 	TraceAttributeValue,
 	TraceConfig,
 	TraceSpan,
 } from "../types.js";
+import {
+	type DiagnosticRedactor,
+	diagnosticStructuredRedactor,
+	redactDiagnosticAttributeKey,
+	copyDiagnosticAttributeTypes,
+	redactedKeyAllocator,
+	isRedactedKey,
+	redactCriticalDiagnosticText,
+	diagnosticAttributeRedactor,
+	REDACTION_FAILED,
+	redactDiagnosticText,
+} from "./diagnostic-redactor.js";
 import { exportSpansOTLP, type OTLPExportOptions } from "./otlp.js";
+import { REDACTED_QUERY_VALUE } from "./request-options.js";
 
 export type SpanAttributeValue = TraceAttributeValue;
 
@@ -19,6 +32,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. */
@@ -42,7 +57,7 @@ type PendingSpan = {
 	startedAt: number;
 	parentId?: string;
 	sequence: number;
-	attributes: Record<string, SpanAttributeValue>;
+	attributes: Record<string, SpanAttributeValue | bigint>;
 };
 
 type CompletedSpanEntry = {
@@ -52,14 +67,22 @@ type CompletedSpanEntry = {
 	exported: boolean;
 };
 
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for(
+	"@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer",
+);
+
+type ResourceAttributesWithSanitizer = Record<string, string> & {
+	[TRACE_RESOURCE_ATTRIBUTE_SANITIZER]?: (
+		attributes: Record<string, string>,
+	) => Record<string, string>;
+};
+
 export interface TraceRecorder {
 	runSpan<T>(name: string, fn: () => Promise<T> | T, options?: SpanHookOptions<T>): Promise<T>;
 }
 
 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",
-);
+const TRACE_EXPORT_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/trace-export-metadata");
 
 type TraceExportMetadata = {
 	update(input: { traceId?: string; resourceAttributes?: Record<string, string> }): void;
@@ -109,30 +132,104 @@ export function resolveTraceContextOptions(config?: TraceConfig): CreateTraceCon
 	};
 }
 
-function normalizeAttributeValue(value: unknown): SpanAttributeValue | undefined {
-	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-		return value;
+function normalizeAttributeValue(
+	value: unknown,
+	redact?: DiagnosticRedactor,
+	retainBigints = false,
+): SpanAttributeValue | bigint | undefined {
+	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: Record<string, unknown> | undefined,
+	redact: DiagnosticRedactor | undefined,
+	retainBigints: true,
+): Record<string, SpanAttributeValue | bigint>;
+function normalizeAttributes(
+	attributes?: Record<string, unknown>,
+	redact?: DiagnosticRedactor,
+): Record<string, SpanAttributeValue>;
 function normalizeAttributes(
 	attributes?: Record<string, unknown>,
-): Record<string, SpanAttributeValue> {
+	redact?: DiagnosticRedactor,
+	retainBigints = false,
+): Record<string, SpanAttributeValue | bigint> {
 	if (!attributes) {
 		return {};
 	}
 
+	const nextKey = redactedKeyAllocator(Object.keys(attributes));
 	const normalizedEntries = Object.entries(attributes)
-		.map(([key, value]) => [key, normalizeAttributeValue(value)] as const)
-		.filter((entry): entry is readonly [string, SpanAttributeValue] => entry[1] !== undefined);
+		.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] as const;
+		})
+		.filter(
+			(entry): entry is readonly [string, SpanAttributeValue | bigint] => entry[1] !== undefined,
+		);
+
+	return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(normalizedEntries));
+}
 
-	return Object.fromEntries(normalizedEntries);
+function prepareResourceAttributesForExport(
+	attributes: Record<string, string> | undefined,
+	redact?: DiagnosticRedactor,
+	sanitize?: (attributes: Record<string, string>) => Record<string, string>,
+): Record<string, string> | undefined {
+	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(
@@ -158,7 +255,10 @@ function prepareSpanForExport(
 	span: Span,
 	sanitize: CreateTraceContextOptions["sanitizeSpanForExport"],
 ): Span {
-	const copy: Span = { ...span, attributes: { ...span.attributes } };
+	const copy: Span = {
+		...span,
+		attributes: copyDiagnosticAttributeTypes(span.attributes, { ...span.attributes }),
+	};
 	if (!sanitize) return copy;
 	const sanitized = sanitize(copy);
 	if (!sanitized || typeof sanitized !== "object") {
@@ -171,6 +271,25 @@ export function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null
 	return (trace as Partial<InternalTraceContext>)[TRACE_RECORDER] ?? null;
 }
 
+const droppedOTLPSpans = new Map<string, number>();
+
+/** Internal, read-only process counters; no reset can re-arm a warning. */
+export function getDroppedOTLPSpanCount(reason: string): number {
+	return droppedOTLPSpans.get(reason) ?? 0;
+}
+
+function warnDroppedOTLPSpans(reason: string, count: number): void {
+	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: CreateTraceContextOptions = {}): TraceContext {
 	if (options.traceId !== undefined) assertValidTraceId(options.traceId);
 	const maxSpans = options.maxSpans ?? 1000;
@@ -180,9 +299,14 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 	// 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 as
+		| ResourceAttributesWithSanitizer
+		| undefined;
+	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, "");
@@ -203,15 +327,30 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 			if (pending.length === 0) return;
 			// Sanitization runs off the request path; a faulty sanitizer drops the batch, never the request.
 			let spans: Span[];
+			let resourceAttributes: Record<string, string> | undefined;
 			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);
 		});
 	};
 
@@ -219,11 +358,11 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 		async runSpan(name, fn, spanOptions = {}) {
 			const pendingSpan: 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 = (
@@ -235,7 +374,7 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 				const duration = endedAt - pendingSpan.startedAt;
 				const attributes = {
 					...pendingSpan.attributes,
-					...normalizeAttributes(extraAttributes),
+					...extraAttributes,
 				};
 
 				if (attributes.duration_ms === undefined) {
@@ -243,15 +382,18 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 				}
 
 				const span: 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(

package/src/schema.ts

@@ -105,6 +105,8 @@ export type SensitiveFieldKind =
 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;
 	/**
@@ -208,10 +210,27 @@ export function field<TSchema extends ZodType>(
 			? 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 }
+			: {}),
 	});
 }
 
@@ -222,6 +241,18 @@ export function sensitive<TSchema extends ZodType>(
 	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<TSchema extends ZodType>(schema: TSchema): TSchema {
+	return field(schema, { sensitive: false });
+}
+
 function sensitiveString(
 	kind: SensitiveFieldKind,
 	description: string,
@@ -382,6 +413,36 @@ function readZodMetadata(schema: unknown): object | undefined {
 	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: unknown, seen = new Set<unknown>()): boolean {
+	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: object): unknown[] {
+	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: unknown): object | undefined {
 	if (!schema || typeof schema !== "object") return undefined;
 	const def = Reflect.get(schema, "def") ?? Reflect.get(schema, "_def");

package/src/server/index.ts

@@ -128,3 +128,20 @@ export {
 	OperationRequestSchema,
 	OperationSuccessResponseSchema,
 } from "./types.js";
+
+export {
+	NativeTelemetryCollector,
+	type NativeAttemptSample,
+	type NativeConnectTelemetryEvent,
+	type NativeLifecycleTelemetryEvent,
+	type NativeTelemetryDiagnostics,
+	type NativeTelemetryErrorCode,
+	type NativeTelemetryHeaderPayload,
+	type NativeTelemetryKind,
+	type NativeTelemetryLifecycleKind,
+	type NativeTelemetryLogPayload,
+	type NativeTelemetryOutcome,
+	type NativeTelemetrySink,
+	type NativeTelemetryVendorSkipReason,
+	type NativeVendorSkipTelemetryEvent,
+} from "../runtime/native-telemetry.js";

package/src/server/self-test-redaction.ts

@@ -1,8 +1,8 @@
 import type { ProviderDefinition } from "../types.js";
 import {
-	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
-	PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
-} from "./self-test-token.js";
+	collectDiagnosticSensitiveValues,
+	SELF_TEST_SENSITIVE_SOURCE_KINDS,
+} from "./sensitive-values.js";
 
 export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
 
@@ -31,39 +31,12 @@ export function collectSelfTestSensitiveValues(
 		credentialInputs?: Readonly<Record<string, string>>;
 	} = {},
 ): string[] {
-	const env = options.env ?? process.env;
-	const envNames = new Set<string>([
-		PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
-		PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
-	]);
-	for (const secret of provider.secrets ?? []) {
-		envNames.add(secret.name);
-	}
-	const healthProbe = provider.healthProbe ?? provider.healthMonitor;
-	for (const name of healthProbe?.requiredSecrets ?? []) {
-		envNames.add(name);
-	}
-	for (const name of Object.values(healthProbe?.credentialInputs ?? {})) {
-		envNames.add(name);
-	}
-
-	const values = new Set<string>();
-	for (const name of envNames) {
-		const value = env[name];
-		if (typeof value === "string" && value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
-			values.add(value);
-		}
-	}
-	for (const value of Object.values(options.credentialInputs ?? {})) {
-		if (value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
-			values.add(value);
-		}
-	}
-	return [...values];
-}
-
-function escapeRegExp(value: string): string {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return collectDiagnosticSensitiveValues(provider, {
+		...options,
+		sourceKinds: SELF_TEST_SENSITIVE_SOURCE_KINDS,
+		minimumLength: MIN_SENSITIVE_VALUE_LENGTH,
+		includeResolvedEnvVariants: false,
+	});
 }
 
 /**
@@ -79,10 +52,7 @@ export function redactSelfTestText(
 	let redacted = text;
 	for (const value of sensitiveValues) {
 		if (value.length < MIN_SENSITIVE_VALUE_LENGTH) continue;
-		redacted = redacted.replace(
-			new RegExp(escapeRegExp(value), "g"),
-			SELF_TEST_REDACTED_PLACEHOLDER,
-		);
+		redacted = redacted.replaceAll(value, SELF_TEST_REDACTED_PLACEHOLDER);
 	}
 	for (const pattern of HEADER_SHAPED_SECRETS) {
 		redacted = redacted.replace(