@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/cache-telemetry.d.ts

@@ -0,0 +1,71 @@
+import type { ProviderCacheLookupMeta } from "../types.js";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type CacheTelemetrySource = "memory" | "redis" | "loader";
+export type CacheTelemetrySample = {
+    key: string;
+    hit: boolean;
+    stale: boolean;
+    ageMs?: number;
+    source: CacheTelemetrySource;
+};
+export type CacheTelemetryLogPayload = {
+    telemetryFailed?: true;
+    lookups: number;
+    hits: number;
+    stale: number;
+    misses: number;
+    writes: number;
+    loaderErrors: number;
+    writeErrors: number;
+    source: {
+        memory: number;
+        redis: number;
+        loader: number;
+    };
+    redisFallbacks: number;
+    redisMode: ClosedEnum<"not_configured" | "configured" | "degraded">;
+    /** Successful Redis commands, including reads, writes, and deletes; memory-only work counts zero. */
+    redisRoundTrips: number;
+    ageMs?: {
+        p50: number;
+        max: number;
+    };
+    samples: CacheTelemetrySample[];
+    dropped: number;
+};
+export type CacheTelemetryHeaderPayload = Omit<CacheTelemetryLogPayload, "samples" | "ageMs" | "telemetryFailed"> & {
+    ageP50?: number;
+    ageMax?: number;
+};
+export interface CacheTelemetrySink {
+    markTelemetryFailed?(): void;
+    setRedisConfigured?(configured: boolean): void;
+    recordLookup(meta: ProviderCacheLookupMeta): void;
+    recordWrite(): void;
+    recordLoaderError?(): void;
+    recordWriteError?(): void;
+    recordRedisFallback(): void;
+    recordRedisRoundTrip?(): void;
+}
+/** Internal construction binding; keeps sink plumbing off ProviderCacheOptions. */
+export declare function bindCacheTelemetry<T extends object>(options: T, sink: CacheTelemetrySink | undefined): T;
+/** Internal lookup used only by the cache factory. */
+export declare function cacheTelemetryFor(options: object): CacheTelemetrySink | undefined;
+export declare function guardCacheTelemetry(sink: CacheTelemetrySink | undefined): CacheTelemetrySink;
+export declare class CacheTelemetryCollector implements TelemetryContributor<CacheTelemetryLogPayload, CacheTelemetryHeaderPayload>, CacheTelemetrySink {
+    #private;
+    readonly key: "cache";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    setRedisConfigured(configured: boolean): void;
+    markTelemetryFailed(): void;
+    recordLookup(meta: ProviderCacheLookupMeta): void;
+    recordWrite(): void;
+    recordLoaderError(): void;
+    recordWriteError(): void;
+    recordRedisFallback(): void;
+    recordRedisRoundTrip(): void;
+    toLogPayload(_spans: SpanIndex): CacheTelemetryLogPayload | undefined;
+    toHeaderPayload(log: CacheTelemetryLogPayload): CacheTelemetryHeaderPayload;
+}

package/dist/runtime/cache-telemetry.js

@@ -0,0 +1,177 @@
+import { Buffer } from "node:buffer";
+import { closedEnum, } from "./request-telemetry.js";
+import { createTelemetryObserver } from "./http-telemetry-guard.js";
+const cacheTelemetryBindings = new WeakMap();
+/** Internal construction binding; keeps sink plumbing off ProviderCacheOptions. */
+export function bindCacheTelemetry(options, sink) {
+    if (sink)
+        cacheTelemetryBindings.set(options, sink);
+    return options;
+}
+/** Internal lookup used only by the cache factory. */
+export function cacheTelemetryFor(options) {
+    return cacheTelemetryBindings.get(options);
+}
+export function guardCacheTelemetry(sink) {
+    const observe = createTelemetryObserver(sink);
+    return {
+        setRedisConfigured: (configured) => observe(() => sink?.setRedisConfigured?.(configured)),
+        recordLookup: (meta) => observe(() => sink?.recordLookup(meta)),
+        recordWrite: () => observe(() => sink?.recordWrite()),
+        recordLoaderError: () => observe(() => sink?.recordLoaderError?.()),
+        recordWriteError: () => observe(() => sink?.recordWriteError?.()),
+        recordRedisFallback: () => observe(() => sink?.recordRedisFallback()),
+        recordRedisRoundTrip: () => observe(() => sink?.recordRedisRoundTrip?.()),
+    };
+}
+const MAX_SAMPLES = 24;
+const MAX_TEXT = 300;
+function integer(value) {
+    return Number.isFinite(value)
+        ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+        : Number.MAX_SAFE_INTEGER;
+}
+function add(a, b) {
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function boundedText(value, redact) {
+    let result;
+    try {
+        result = redact?.(value) ?? value;
+    }
+    catch {
+        result = "[REDACTION_FAILED]";
+    }
+    const length = Math.min(result.length, MAX_TEXT);
+    const units = Buffer.alloc(length * 2);
+    for (let index = 0; index < length; index += 1)
+        units.writeUInt16LE(result.charCodeAt(index), index * 2);
+    return units.toString("utf16le");
+}
+export class CacheTelemetryCollector {
+    key = "cache";
+    #redact;
+    #telemetryFailed = false;
+    #lookups = 0;
+    #hits = 0;
+    #stale = 0;
+    #misses = 0;
+    #writes = 0;
+    #loaderErrors = 0;
+    #writeErrors = 0;
+    #source = { memory: 0, redis: 0, loader: 0 };
+    #redisFallbacks = 0;
+    #configured;
+    #redisRoundTrips = 0;
+    #ages = [];
+    #maxAge = 0;
+    #samples = [];
+    #dropped = 0;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+        this.#configured = "not_configured";
+    }
+    setRedisConfigured(configured) {
+        if (configured && this.#configured === "not_configured")
+            this.#configured = "configured";
+    }
+    markTelemetryFailed() {
+        this.#telemetryFailed = true;
+    }
+    recordLookup(meta) {
+        if (!["memory", "redis", "loader"].includes(meta.source)) {
+            this.#telemetryFailed = true;
+            return;
+        }
+        this.#lookups = add(this.#lookups, 1);
+        if (meta.hit)
+            this.#hits = add(this.#hits, 1);
+        else
+            this.#misses = add(this.#misses, 1);
+        if (meta.stale)
+            this.#stale = add(this.#stale, 1);
+        this.#source[meta.source] = add(this.#source[meta.source], 1);
+        if (meta.source === "redis" && this.#configured === "not_configured")
+            this.#configured = "configured";
+        if (meta.ageMs !== undefined) {
+            const age = integer(meta.ageMs);
+            if (this.#ages.length < MAX_SAMPLES)
+                this.#ages.push(age);
+            this.#maxAge = Math.max(this.#maxAge, age);
+        }
+        if (this.#samples.length < MAX_SAMPLES) {
+            this.#samples.push({
+                key: boundedText(meta.key, this.#redact),
+                hit: meta.hit,
+                stale: meta.stale,
+                ...(meta.ageMs === undefined ? {} : { ageMs: integer(meta.ageMs) }),
+                source: meta.source,
+            });
+        }
+        else
+            this.#dropped = add(this.#dropped, 1);
+    }
+    recordWrite() {
+        this.#writes = add(this.#writes, 1);
+    }
+    recordLoaderError() {
+        this.#loaderErrors = add(this.#loaderErrors, 1);
+    }
+    recordWriteError() {
+        this.#writeErrors = add(this.#writeErrors, 1);
+    }
+    recordRedisFallback() {
+        this.#redisFallbacks = add(this.#redisFallbacks, 1);
+        this.#configured = "degraded";
+    }
+    recordRedisRoundTrip() {
+        this.#redisRoundTrips = add(this.#redisRoundTrips, 1);
+    }
+    toLogPayload(_spans) {
+        if (this.#lookups === 0 &&
+            this.#writes === 0 &&
+            this.#redisFallbacks === 0 &&
+            !this.#telemetryFailed)
+            return undefined;
+        const sorted = [...this.#ages].sort((a, b) => a - b);
+        const p50 = sorted.length ? sorted[Math.floor((sorted.length - 1) / 2)] : undefined;
+        return {
+            ...(this.#telemetryFailed ? { telemetryFailed: true } : {}),
+            lookups: this.#lookups,
+            hits: this.#hits,
+            stale: this.#stale,
+            misses: this.#misses,
+            writes: this.#writes,
+            loaderErrors: this.#loaderErrors,
+            writeErrors: this.#writeErrors,
+            source: { ...this.#source },
+            redisFallbacks: this.#redisFallbacks,
+            redisMode: closedEnum(this.#configured),
+            redisRoundTrips: this.#redisRoundTrips,
+            ...(p50 === undefined ? {} : { ageMs: { p50, max: this.#maxAge } }),
+            samples: this.#samples.map((sample) => ({ ...sample })),
+            dropped: this.#dropped,
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            lookups: log.lookups,
+            hits: log.hits,
+            stale: log.stale,
+            misses: log.misses,
+            writes: log.writes,
+            loaderErrors: log.loaderErrors,
+            writeErrors: log.writeErrors,
+            source: {
+                memory: log.source.memory,
+                redis: log.source.redis,
+                loader: log.source.loader,
+            },
+            redisFallbacks: log.redisFallbacks,
+            redisMode: log.redisMode,
+            redisRoundTrips: log.redisRoundTrips,
+            ...(log.ageMs ? { ageP50: log.ageMs.p50, ageMax: log.ageMs.max } : {}),
+            dropped: log.dropped,
+        };
+    }
+}

package/dist/runtime/cache.d.ts

@@ -5,6 +5,9 @@ export type ProviderCacheOptions = {
     memoryMaxEntries?: number;
     now?: () => number;
 };
+export declare const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
 export declare function createProviderCache(options: ProviderCacheOptions): ProviderCache;
+/** Internal cache capability, separate from hit/miss metadata. */
+export declare function isProviderCacheBypassed(cache: ProviderCache): boolean;
 export declare function createBypassProviderCache(options: Pick<ProviderCacheOptions, "providerId">): ProviderCache;
 export declare function resetProviderCacheForTests(): void;

package/dist/runtime/cache.js

@@ -1,9 +1,14 @@
-import { createHash } from "node:crypto";
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createHash, createHmac } from "node:crypto";
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
+import { cacheTelemetryFor, guardCacheTelemetry } from "./cache-telemetry.js";
 import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
+export const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
 const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
 const DEFAULT_MEMORY_MAX_ENTRIES = 1_000;
 const DEFAULT_REDIS_TIMEOUT_MS = 150;
+const SECRET_SCOPED_KEY_MARKER = "[secret-scoped";
 const SECRET_FIELD_NAMES = new Set([
     "authorization",
     "cookie",
@@ -18,6 +23,7 @@ const SECRET_FIELD_NAMES = new Set([
     "refresh_token",
 ]);
 const sharedBackends = new Map();
+let warnedAboutUnpepperedSecretKeys = false;
 function backendKey(redisUrl) {
     return redisUrl ?? "memory";
 }
@@ -55,20 +61,157 @@ function shouldRedactField(name, extra) {
         normalized.includes("password") ||
         normalized.includes("secret"));
 }
-function normalizeKeyPart(value, extra) {
+function unsupportedSecretValue(path, reason) {
+    throw new ProviderError(`Secret cache-key values must be JSON-safe; ${reason} at ${path}.`, {
+        code: "CACHE_KEY_SECRET_VALUE_UNSUPPORTED",
+        fix: "Convert the secret cache-key selector to JSON-safe primitives, arrays, or plain objects.",
+    });
+}
+function assertJsonSafeSecretValue(value, reportedPath, ancestors = new Set()) {
+    if (value === undefined)
+        return;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            unsupportedSecretValue(reportedPath, "non-finite numbers are unsupported");
+        if (Object.is(value, -0))
+            unsupportedSecretValue(reportedPath, "negative zero is unsupported");
+        return;
+    }
+    if (typeof value !== "object") {
+        unsupportedSecretValue(reportedPath, `${typeof value} values are unsupported`);
+    }
+    if (ancestors.has(value))
+        unsupportedSecretValue(reportedPath, "cyclic values are unsupported");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                unsupportedSecretValue(reportedPath, "symbol-keyed array properties are unsupported");
+            }
+            const expectedNames = new Set(["length"]);
+            for (let index = 0; index < value.length; index += 1) {
+                const key = String(index);
+                expectedNames.add(key);
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor)
+                    unsupportedSecretValue(reportedPath, "sparse arrays are unsupported");
+                if (!descriptor.enumerable || !("value" in descriptor)) {
+                    unsupportedSecretValue(reportedPath, "array accessors are unsupported");
+                }
+                assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+            }
+            if (Object.getOwnPropertyNames(value).some((name) => !expectedNames.has(name))) {
+                unsupportedSecretValue(reportedPath, "custom array properties are unsupported");
+            }
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            unsupportedSecretValue(reportedPath, "non-plain objects are unsupported");
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            unsupportedSecretValue(reportedPath, "symbol-keyed properties are unsupported");
+        }
+        for (const key of Object.getOwnPropertyNames(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !("value" in descriptor)) {
+                unsupportedSecretValue(reportedPath, "non-enumerable properties and accessors are unsupported");
+            }
+            assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function containsUndefined(value) {
+    if (value === undefined)
+        return true;
+    if (Array.isArray(value))
+        return value.some(containsUndefined);
+    if (isRecord(value))
+        return Object.values(value).some(containsUndefined);
+    return false;
+}
+function tagSecretValue(value) {
+    if (value === undefined)
+        return ["undefined"];
+    if (value === null)
+        return ["null"];
+    if (typeof value === "string")
+        return ["string", value];
+    if (typeof value === "number")
+        return ["number", value];
+    if (typeof value === "boolean")
+        return ["boolean", value];
+    if (Array.isArray(value))
+        return ["array", value.map(tagSecretValue)];
+    return [
+        "object",
+        Object.entries(value).map(([key, entry]) => [
+            key,
+            tagSecretValue(entry),
+        ]),
+    ];
+}
+function serializeSecretValue(value) {
+    if (!containsUndefined(value))
+        return JSON.stringify([value]);
+    return `undefined-v1:${JSON.stringify(tagSecretValue(value))}`;
+}
+function warnAboutUnpepperedSecretKey() {
+    if (warnedAboutUnpepperedSecretKeys)
+        return;
+    warnedAboutUnpepperedSecretKeys = true;
+    console.warn(JSON.stringify({
+        level: "warn",
+        event: "provider_cache_secret_key_unpeppered",
+        message: `Secret-bearing cache keys are using unkeyed SHA-256 because ${APIFUSE__CACHE__KEY_PEPPER_ENV} is not configured.`,
+    }));
+}
+function normalizeKeyPart(value, extra, pepper) {
     if (Array.isArray(value)) {
-        return value.map((entry) => normalizeKeyPart(entry, extra));
+        const entries = value.map((entry) => normalizeKeyPart(entry, extra, pepper));
+        return {
+            value: entries.map((entry) => entry.value),
+            secretScoped: entries.some((entry) => entry.secretScoped),
+        };
     }
     if (isRecord(value)) {
-        const normalized = {};
+        const normalized = Object.create(null);
+        let secretScoped = false;
         for (const key of Object.keys(value).sort()) {
-            if (shouldRedactField(key, extra))
-                continue;
-            normalized[key] = normalizeKeyPart(value[key], extra);
+            const part = shouldRedactField(key, extra)
+                ? hashSecretValue(value[key], key, extra, pepper)
+                : normalizeKeyPart(value[key], extra, pepper);
+            normalized[key] = part.value;
+            secretScoped ||= part.secretScoped;
         }
-        return normalized;
+        return { value: normalized, secretScoped };
+    }
+    return { value, secretScoped: false };
+}
+function hashSecretValue(value, fieldName, extra, pepper) {
+    assertJsonSafeSecretValue(value, `${fieldName} (inside secret value)`);
+    const canonical = serializeSecretValue(normalizeKeyPart(value, extra, pepper).value);
+    if (pepper === undefined) {
+        warnAboutUnpepperedSecretKey();
+        const digest = createHash("sha256").update(canonical).digest("hex");
+        return { value: `sha256:${digest}`, secretScoped: true };
     }
-    return value;
+    const digest = createHmac("sha256", pepper).update(canonical).digest("hex");
+    return { value: `hmac-sha256:${digest}`, secretScoped: true };
+}
+function metadataKeys(events, secretScopedKeys) {
+    let secretScopedIndex = 0;
+    return Array.from(new Set(events.map((event) => event.key))).map((key) => {
+        if (!secretScopedKeys.has(key))
+            return key;
+        secretScopedIndex += 1;
+        return `${SECRET_SCOPED_KEY_MARKER}#${secretScopedIndex}]`;
+    });
 }
 function stableHash(value) {
     return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 32);
@@ -138,12 +281,19 @@ async function withRedisFallback(operation) {
 }
 export function createProviderCache(options) {
     const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+    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);
     const now = options.now ?? Date.now;
     const events = [];
+    const telemetry = guardCacheTelemetry(cacheTelemetryFor(options));
+    telemetry.setRedisConfigured?.(!!redisUrl);
+    let redisUnavailable = false;
+    const secretScopedKeys = new Set();
     function record(meta) {
         events.push(meta);
+        telemetry?.recordLookup(meta);
     }
     function sweepMemory(currentTime) {
         for (const [entryKey, entry] of backend.memory) {
@@ -177,13 +327,21 @@ export function createProviderCache(options) {
     async function readRedis(key, currentTime) {
         const redis = backend.redis;
         if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+            if (redis) {
+                redisUnavailable = true;
+                telemetry?.recordRedisFallback();
+            }
             return null;
         }
         const raw = await withRedisFallback(async () => {
             return await redis.get(key);
         });
-        if (typeof raw !== "string" && raw !== null)
+        if (typeof raw !== "string" && raw !== null) {
+            redisUnavailable = true;
+            telemetry.recordRedisFallback();
             return null;
+        }
+        telemetry?.recordRedisRoundTrip?.();
         const envelope = safeParseEnvelope(raw);
         if (!envelope)
             return null;
@@ -225,6 +383,7 @@ export function createProviderCache(options) {
         return staleMemoryResult;
     }
     async function write(key, value, cacheOptions) {
+        telemetry?.recordWrite();
         const currentTime = now();
         const freshTtlMs = jitteredTtlMs(cacheOptions.ttlMs, cacheOptions.jitterPct);
         const staleIfErrorMs = cacheOptions.staleIfErrorMs ?? 0;
@@ -238,9 +397,21 @@ export function createProviderCache(options) {
         rememberEnvelope(key, envelope, currentTime);
         const redis = backend.redis;
         if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+            if (redis) {
+                redisUnavailable = true;
+                telemetry?.recordRedisFallback();
+                telemetry?.recordWriteError?.();
+            }
             return;
         }
-        await withRedisFallback(() => redis.set(key, JSON.stringify(envelope), "PX", staleTtlMs));
+        const written = await withRedisFallback(() => redis.set(key, JSON.stringify(envelope), "PX", staleTtlMs));
+        if (written === undefined) {
+            redisUnavailable = true;
+            telemetry?.recordRedisFallback();
+            telemetry?.recordWriteError?.();
+        }
+        else
+            telemetry?.recordRedisRoundTrip?.();
     }
     async function loadAndStore(key, loader, cacheOptions, staleCandidate) {
         try {
@@ -260,29 +431,53 @@ export function createProviderCache(options) {
             if (staleCandidate?.meta.stale) {
                 return staleCandidate;
             }
+            telemetry?.recordLookup({
+                key,
+                hit: false,
+                stale: false,
+                source: "loader",
+            });
+            telemetry?.recordLoaderError?.();
             throw error;
         }
     }
     return {
         key(namespace, parts, keyOptions) {
             const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-            const normalized = normalizeKeyPart(parts, extra);
-            return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+            const normalized = normalizeKeyPart(parts, extra, pepper);
+            const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+            if (normalized.secretScoped)
+                secretScopedKeys.add(key);
+            return key;
         },
         async get(key) {
             const result = await read(key);
             if (result)
                 record(result.meta);
+            else
+                telemetry.recordLookup({
+                    key,
+                    hit: false,
+                    stale: false,
+                    source: backend.redis && !redisUnavailable ? "redis" : "memory",
+                });
             return result;
         },
         set: write,
         async delete(key) {
+            telemetry?.recordWrite();
             backend.memory.delete(key);
             const redis = backend.redis;
             if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+                if (redis)
+                    telemetry?.recordRedisFallback();
                 return;
             }
-            await withRedisFallback(() => redis.del(key));
+            const deleted = await withRedisFallback(() => redis.del(key));
+            if (deleted === undefined)
+                telemetry?.recordRedisFallback();
+            else
+                telemetry?.recordRedisRoundTrip?.();
         },
         async getOrSet(key, loader, cacheOptions) {
             const existing = await read(key);
@@ -292,10 +487,23 @@ export function createProviderCache(options) {
             }
             const existingInflight = backend.inflight.get(key);
             if (existingInflight) {
-                const inflightResult = await existingInflight;
-                const result = resultWithValue(inflightResult.value, inflightResult.meta);
-                record(result.meta);
-                return result;
+                try {
+                    const inflightResult = await existingInflight;
+                    const result = resultWithValue(inflightResult.value, inflightResult.meta);
+                    record(result.meta);
+                    return result;
+                }
+                catch (error) {
+                    const meta = {
+                        key,
+                        hit: false,
+                        stale: false,
+                        source: "loader",
+                    };
+                    telemetry.recordLookup(meta);
+                    telemetry?.recordLoaderError?.();
+                    throw error;
+                }
             }
             const promise = loadAndStore(key, loader, cacheOptions, existing).finally(() => {
                 backend.inflight.delete(key);
@@ -312,19 +520,30 @@ export function createProviderCache(options) {
             return {
                 hit: events.some((event) => event.hit),
                 stale: events.some((event) => event.stale),
-                keys: Array.from(new Set(events.map((event) => event.key))),
+                keys: metadataKeys(events, secretScopedKeys),
                 source: sourceSummary(events),
             };
         },
     };
 }
+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 = readDiagnosticEnv(APIFUSE__CACHE__KEY_PEPPER_ENV);
+    const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
     const events = [];
-    return {
+    const secretScopedKeys = new Set();
+    const cache = {
         key(namespace, parts, keyOptions) {
             const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-            const normalized = normalizeKeyPart(parts, extra);
-            return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+            const normalized = normalizeKeyPart(parts, extra, pepper);
+            const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+            if (normalized.secretScoped)
+                secretScopedKeys.add(key);
+            return key;
         },
         async get(_key) {
             return null;
@@ -352,11 +571,13 @@ export function createBypassProviderCache(options) {
             return {
                 hit: false,
                 stale: false,
-                keys: Array.from(new Set(events.map((event) => event.key))),
+                keys: metadataKeys(events, secretScopedKeys),
                 source: sourceSummary(events),
             };
         },
     };
+    bypassCaches.add(cache);
+    return cache;
 }
 export function resetProviderCacheForTests() {
     for (const backend of sharedBackends.values()) {
@@ -365,4 +586,5 @@ export function resetProviderCacheForTests() {
         backend.redis?.disconnect();
     }
     sharedBackends.clear();
+    warnedAboutUnpepperedSecretKeys = false;
 }

package/dist/runtime/capability-response.d.ts

@@ -0,0 +1,3 @@
+export declare const CAPABILITY_BODY_UNAVAILABLE = "<body unavailable>";
+/** Read optional diagnostic response text without letting a body stall the request failure. */
+export declare function readCapabilityErrorBody(response: Response, signal: AbortSignal): Promise<string>;