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

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;

package/dist/server/index.d.ts

@@ -12,3 +12,4 @@ export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, 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/dist/server/index.js

@@ -6,3 +6,4 @@ export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js"
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
+export { NativeTelemetryCollector, } from "../runtime/native-telemetry.js";

package/dist/server/self-test-redaction.js

@@ -1,4 +1,4 @@
-import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token.js";
+import { collectDiagnosticSensitiveValues, SELF_TEST_SENSITIVE_SOURCE_KINDS, } from "./sensitive-values.js";
 export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
 /** Maximum length of any string echoed in a self-test response. */
 export const SELF_TEST_MAX_TEXT_LENGTH = 300;
@@ -16,37 +16,12 @@ const HEADER_SHAPED_SECRETS = [
  * credential inputs.
  */
 export function collectSelfTestSensitiveValues(provider, options = {}) {
-    const env = options.env ?? process.env;
-    const envNames = new Set([
-        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();
-    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) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return collectDiagnosticSensitiveValues(provider, {
+        ...options,
+        sourceKinds: SELF_TEST_SENSITIVE_SOURCE_KINDS,
+        minimumLength: MIN_SENSITIVE_VALUE_LENGTH,
+        includeResolvedEnvVariants: false,
+    });
 }
 /**
  * Scrubs known secret values and header-shaped credentials from a string and
@@ -58,7 +33,7 @@ export function redactSelfTestText(text, sensitiveValues, maxLength = SELF_TEST_
     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(pattern, (_match, prefix) => `${prefix}${SELF_TEST_REDACTED_PLACEHOLDER}`);

package/dist/server/sensitive-values.d.ts

@@ -0,0 +1,26 @@
+import type { ProviderDefinition } from "../types.js";
+export declare const SELF_TEST_SENSITIVE_SOURCE_KINDS: readonly ["selfTestMasterSecrets", "providerSecrets", "healthProbeSecrets", "requestCredentials"];
+/** Explicit source allowlist: no environment-name or payload-shape secret sweep. */
+export declare const DIAGNOSTIC_SENSITIVE_SOURCE_KINDS: readonly ["selfTestMasterSecrets", "providerSecrets", "healthProbeSecrets", "requestCredentials", "engineProxyCredentials", "engineSolverKeys", "engineCeremonyLeaseCredentials", "ocrCredentials", "sttCredentials", "cdpCredentials", "statefulForwardingSecret", "redisCredentials", "otlpHeaders", "cacheKeyPepper", "sensitiveParams"];
+export type DiagnosticSensitiveSourceKind = (typeof DIAGNOSTIC_SENSITIVE_SOURCE_KINDS)[number];
+/**
+ * Startup inventory; request-scoped readers additionally register live values on access.
+ */
+export declare function collectStaticDiagnosticSensitiveValues(provider: ProviderDefinition, options?: {
+    env?: Readonly<Record<string, string | undefined>>;
+    statefulForwardingSecret?: string;
+}): string[];
+/** Generalised self-test collector, also used to seed and enrich ordinary request scopes. */
+export declare function collectDiagnosticSensitiveValues(provider: ProviderDefinition, options?: {
+    env?: Readonly<Record<string, string | undefined>>;
+    credentialInputs?: Readonly<Record<string, unknown>>;
+    connectionSecrets?: Readonly<Record<string, string | undefined>>;
+    sensitiveParams?: readonly string[];
+    statefulForwardingSecret?: string;
+    sourceKinds?: readonly DiagnosticSensitiveSourceKind[];
+    minimumLength?: number;
+    /** Preserve the legacy self-test response collector when false. */
+    includeResolvedEnvVariants?: boolean;
+}): string[];
+/** Derive the live-read allowlist from the same collector as the startup inventory. */
+export declare function createDiagnosticEnvObserver(provider: ProviderDefinition, register: (values: readonly string[]) => void, has?: (value: string) => boolean): (name: string, value: string) => void;

package/dist/server/sensitive-values.js

@@ -0,0 +1,128 @@
+import { resolvedStringVariants, urlCredentialComponents, otlpHeaderCredentialValues, } from "../runtime/diagnostic-env-values.js";
+import { PROVIDER_CACHE_REDIS_URL_ENV, PROVIDER_STATE_REDIS_URL_ENV, REDIS_URL_ENV, } from "../config/loader.js";
+import { ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, } from "../engine.js";
+import { APIFUSE__CACHE__KEY_PEPPER_ENV } from "../runtime/cache.js";
+import { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "../runtime/egress-lease.js";
+import { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, } from "../runtime/ocr.js";
+import { OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, } from "../runtime/otlp.js";
+import { APIFUSE__CDP_POOL__URL } from "../runtime/resolver-config.js";
+import { APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV } from "../runtime/stt.js";
+import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token.js";
+export const SELF_TEST_SENSITIVE_SOURCE_KINDS = [
+    "selfTestMasterSecrets",
+    "providerSecrets",
+    "healthProbeSecrets",
+    "requestCredentials",
+];
+/** Explicit source allowlist: no environment-name or payload-shape secret sweep. */
+export const DIAGNOSTIC_SENSITIVE_SOURCE_KINDS = [
+    ...SELF_TEST_SENSITIVE_SOURCE_KINDS,
+    "engineProxyCredentials",
+    "engineSolverKeys",
+    "engineCeremonyLeaseCredentials",
+    "ocrCredentials",
+    "sttCredentials",
+    "cdpCredentials",
+    "statefulForwardingSecret",
+    "redisCredentials",
+    "otlpHeaders",
+    "cacheKeyPepper",
+    "sensitiveParams",
+];
+/**
+ * Startup inventory; request-scoped readers additionally register live values on access.
+ */
+export function collectStaticDiagnosticSensitiveValues(provider, options = {}) {
+    return collectDiagnosticSensitiveValues(provider, {
+        ...options,
+        sourceKinds: DIAGNOSTIC_SENSITIVE_SOURCE_KINDS.filter((kind) => kind !== "requestCredentials" && kind !== "sensitiveParams"),
+    });
+}
+/** Generalised self-test collector, also used to seed and enrich ordinary request scopes. */
+export function collectDiagnosticSensitiveValues(provider, options = {}) {
+    const env = options.env ?? process.env;
+    const envValues = (names) => names.map((name) => env[name]);
+    const resolvedEnvValues = (names) => envValues(names).flatMap((value) => value === undefined
+        ? []
+        : options.includeResolvedEnvVariants === false
+            ? [value]
+            : [value, value.trim()]);
+    const healthProbe = provider.healthProbe ?? provider.healthMonitor;
+    const sources = {
+        selfTestMasterSecrets: () => resolvedEnvValues([
+            PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
+            PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
+        ]),
+        providerSecrets: () => resolvedEnvValues((provider.secrets ?? []).map((secret) => secret.name)),
+        healthProbeSecrets: () => resolvedEnvValues([
+            ...(healthProbe?.requiredSecrets ?? []),
+            ...Object.values(healthProbe?.credentialInputs ?? {}),
+        ]),
+        requestCredentials: () => [
+            ...Object.values(options.credentialInputs ?? {}),
+            ...Object.values(options.connectionSecrets ?? {}),
+        ],
+        engineProxyCredentials: () => resolvedEnvValues(ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES),
+        // These are the resolver-config API keys after #251's engine credential projection.
+        engineSolverKeys: () => resolvedEnvValues(ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES),
+        engineCeremonyLeaseCredentials: () => resolvedEnvValues([APIFUSE__ENGINE__CEREMONY_LEASE_KEY]),
+        ocrCredentials: () => resolvedEnvValues([APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__OCR__API_KEY_ENV]),
+        sttCredentials: () => resolvedEnvValues([APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV]),
+        cdpCredentials: () => resolvedStringVariants(env[APIFUSE__CDP_POOL__URL]).flatMap((url) => [
+            url,
+            ...urlCredentialComponents(url, { includePathAndQuery: true }),
+        ]),
+        statefulForwardingSecret: () => resolvedStringVariants(options.statefulForwardingSecret),
+        redisCredentials: () => [PROVIDER_CACHE_REDIS_URL_ENV, PROVIDER_STATE_REDIS_URL_ENV, REDIS_URL_ENV]
+            .flatMap((name) => resolvedStringVariants(env[name]))
+            .flatMap((url) => urlCredentialComponents(url, { includePathAndQuery: false })),
+        otlpHeaders: () => [
+            ...[OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_HEADERS].flatMap((name) => env[name] === undefined ? [] : otlpHeaderCredentialValues(env[name])),
+            ...[OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT].flatMap((name) => resolvedStringVariants(env[name]).flatMap((url) => urlCredentialComponents(url, { includePathAndQuery: false }))),
+        ],
+        cacheKeyPepper: () => resolvedEnvValues([APIFUSE__CACHE__KEY_PEPPER_ENV]),
+        sensitiveParams: () => options.sensitiveParams ?? [],
+    };
+    const values = new Set();
+    for (const kind of options.sourceKinds ?? DIAGNOSTIC_SENSITIVE_SOURCE_KINDS) {
+        for (const value of sources[kind]()) {
+            if (typeof value === "string" && value.length >= (options.minimumLength ?? 1))
+                values.add(value);
+        }
+    }
+    return [...values];
+}
+const diagnosticEnvNames = new WeakMap();
+/** Derive the live-read allowlist from the same collector as the startup inventory. */
+export function createDiagnosticEnvObserver(provider, register, has) {
+    let names = diagnosticEnvNames.get(provider);
+    if (!names) {
+        names = new Set();
+        const captured = names;
+        collectStaticDiagnosticSensitiveValues(provider, {
+            env: new Proxy({}, {
+                get: (_target, key) => {
+                    if (typeof key === "string")
+                        captured.add(key);
+                    return undefined;
+                },
+            }),
+        });
+        diagnosticEnvNames.set(provider, names);
+    }
+    const seen = new Map();
+    return (name, value) => {
+        if (!names.has(name) || seen.get(name) === value)
+            return;
+        if (has?.(value) && has(value.trim()))
+            return;
+        // Includes URL userinfo/CDP components and OTLP auth values, using the same rules.
+        register([
+            ...resolvedStringVariants(value),
+            ...collectStaticDiagnosticSensitiveValues(provider, {
+                env: { [name]: value },
+            }),
+        ]);
+        seen.set(name, value);
+    };
+}

package/dist/server/serve-implementation.d.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { type ProviderEngine } from "../engine.js";
 import { type ProviderErrorObservability } from "../errors.js";
 import { type ProviderErrorCategory } from "../observability.js";
+import type { HandleTelemetryEvent } from "../handle.js";
 import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import { type ResolverTelemetryLogPayload } from "../runtime/resolver-telemetry.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
@@ -115,18 +116,10 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     event: "provider_secrets_missing";
     providerId: string;
     missingSecrets: string[];
-} | {
+} | ({
     level: "info";
-    event: "provider_choice_token";
-    providerId: string;
-    purpose: string;
-    operation: "parse" | "consume";
-    format: "word" | "legacy";
-    outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
-    consumeMode: "never" | "on-parse" | "explicit";
-    consumed: boolean;
-    replay: boolean;
-} | {
+    event: "provider_handle";
+} & HandleTelemetryEvent) | {
     level: "warn";
     event: "provider_cleanup_failed";
     providerId: string;