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

package/dist/runtime/cache.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, createHmac } from "node:crypto";
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
 import { ProviderError } from "../errors.js";
@@ -279,7 +280,7 @@ async function withRedisFallback(operation) {
 }
 export function createProviderCache(options) {
     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);
@@ -465,12 +466,17 @@ export function createProviderCache(options) {
         },
     };
 }
+const bypassCaches = new WeakSet();
+/** Internal cache capability, separate from hit/miss metadata. */
+export function isProviderCacheBypassed(cache) {
+    return bypassCaches.has(cache);
+}
 export function createBypassProviderCache(options) {
-    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 = [];
     const secretScopedKeys = new Set();
-    return {
+    const cache = {
         key(namespace, parts, keyOptions) {
             const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
             const normalized = normalizeKeyPart(parts, extra, pepper);
@@ -510,6 +516,8 @@ export function createBypassProviderCache(options) {
             };
         },
     };
+    bypassCaches.add(cache);
+    return cache;
 }
 export function resetProviderCacheForTests() {
     for (const backend of sharedBackends.values()) {

package/dist/runtime/diagnostic-env-values.d.ts

@@ -0,0 +1,5 @@
+export declare function resolvedStringVariants(value: string | undefined): string[];
+export declare function urlCredentialComponents(value: string, options: {
+    includePathAndQuery: boolean;
+}): string[];
+export declare function otlpHeaderCredentialValues(value: string): string[];

package/dist/runtime/diagnostic-env-values.js

@@ -0,0 +1,57 @@
+export function resolvedStringVariants(value) {
+    if (value === undefined)
+        return [];
+    return [...new Set([value, value.trim()])].filter((candidate) => candidate.length > 0);
+}
+function decodedComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+export function urlCredentialComponents(value, options) {
+    let 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) {
+    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/dist/runtime/diagnostic-env.d.ts

@@ -0,0 +1,11 @@
+import { type CompiledDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
+type EnvObserver = (name: string, value: string) => void;
+export interface DiagnosticEnvScope {
+    observe: EnvObserver;
+    finished: boolean;
+    staticValues?: CompiledDiagnosticSensitiveValues;
+}
+/** Resolve and register atomically, before any consumer can use a live env credential. */
+export declare function readDiagnosticEnv(name: string, env?: Readonly<Record<string, string | undefined>>): string | undefined;
+export declare function withDiagnosticEnv<T>(observer: EnvObserver | DiagnosticEnvScope, fn: () => T): T;
+export {};

package/dist/runtime/diagnostic-env.js

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { resolvedStringVariants, urlCredentialComponents, otlpHeaderCredentialValues, } from "./diagnostic-env-values.js";
+import { registerProcessDiagnosticValues, suppressProcessDiagnosticValues, withAppDiagnosticFallback, } from "./diagnostic-redactor.js";
+const observers = new AsyncLocalStorage();
+/** Resolve and register atomically, before any consumer can use a live env credential. */
+export function readDiagnosticEnv(name, env = process.env) {
+    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(observer, fn) {
+    const scope = typeof observer === "function" ? { observe: observer, finished: false } : observer;
+    const run = () => observers.run(scope, fn);
+    return scope.staticValues ? withAppDiagnosticFallback(scope.staticValues, run) : run();
+}

package/dist/runtime/diagnostic-redactor.d.ts

@@ -0,0 +1,49 @@
+export type DiagnosticRedactor = (text: string) => string;
+export declare const REDACTION_FAILED = "[REDACTION_FAILED]";
+/** Observer failures must never return the original diagnostic, including via ?? fallbacks. */
+export declare function redactDiagnosticText(text: string, redact?: DiagnosticRedactor): string;
+export interface DiagnosticSensitiveRegistry {
+    redact: DiagnosticRedactor;
+    readonly redactCritical: DiagnosticRedactor;
+    readonly redactStructured: DiagnosticRedactor;
+    readonly suppressed: boolean;
+    has(value: string): boolean;
+    add(values: readonly string[]): void;
+    suppress(): void;
+}
+/** Opaque handle: callers cannot modify either of the two independently compiled matchers. */
+export interface CompiledDiagnosticSensitiveValues {
+    readonly kind: "compiled-diagnostic-sensitive-values";
+}
+export declare function compileDiagnosticSensitiveValues(values: readonly string[]): CompiledDiagnosticSensitiveValues;
+/**
+ * Give an independent runtime/configuration evaluation its own fallback lifetime.
+ * Apps created inside the scope retain that inventory, including across awaits and
+ * after the callback returns. Ordinary startup/CLI reads keep the process lifetime.
+ * This also lets test harnesses isolate synthetic env reads without clearing live
+ * apps' credentials or weakening registration, matching, or exhaustion policies.
+ */
+export declare function withDiagnosticFallbackScope<T>(fn: () => T): T;
+/** Re-enter the app's existing lifetime, including for detached request callbacks. */
+export declare function withAppDiagnosticFallback<T>(staticValues: CompiledDiagnosticSensitiveValues, fn: () => T): T;
+export declare function suppressProcessDiagnosticValues(): void;
+export declare function registerProcessDiagnosticValues(values: readonly string[]): void;
+/** The app's static inventory and the shared outside-context fallback form one static part. */
+export declare function compileProcessDiagnosticSensitiveValues(values: readonly string[]): CompiledDiagnosticSensitiveValues;
+/** One small mutable registry per request, composed with precompiled process-static values. */
+export declare function createDiagnosticRedactor(values?: readonly string[], staticValues?: CompiledDiagnosticSensitiveValues): DiagnosticSensitiveRegistry;
+/** Internal binding; neither the registry nor its values enter provider-facing context types. */
+export declare function bindDiagnosticSensitiveRegistry(trace: object, registry: DiagnosticSensitiveRegistry): void;
+export declare function registerDiagnosticSensitiveValues(trace: object, values: readonly string[]): void;
+export declare function bindCriticalDiagnosticRedactor(redact: DiagnosticRedactor, critical: DiagnosticRedactor, structured?: DiagnosticRedactor, isSuppressed?: () => boolean): void;
+export declare function isDiagnosticRedactionSuppressed(redact?: DiagnosticRedactor): boolean;
+/** Typed values and keys still match known credentials, but never blanket suppression. */
+export declare function diagnosticStructuredRedactor(redact?: DiagnosticRedactor): DiagnosticRedactor | undefined;
+export declare function redactDiagnosticAttributeKey(key: string, redact?: DiagnosticRedactor): string;
+export declare function redactCriticalDiagnosticText(text: string, redact?: DiagnosticRedactor): string;
+export declare function diagnosticAttributeRedactor(key: string, redact?: DiagnosticRedactor): DiagnosticRedactor | undefined;
+export declare function isDiagnosticBigintAttribute(attributes: object, key: string): boolean;
+export declare function copyDiagnosticAttributeTypes<T extends Record<string, unknown>>(source: Record<string, unknown>, target: T): T;
+/** Reserve existing keys so independently redacted names never drop an attribute. */
+export declare function redactedKeyAllocator(keys: Iterable<string>): () => string;
+export declare function isRedactedKey(key: string): boolean;