@apifuse/provider-sdk 2.2.0-beta.24 → 2.2.0-beta.25

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.25
+
+- Release candidate for main commit e6df658b95c0728b671fd221919ec2f85f82b0b7.
+
 ## 2.2.0-beta.24
 
 - Release candidate for main commit 0f21a2959dcbb9b96fe426259259d0870cfc537f.

package/bin/apifuse-submit-check.ts

@@ -1691,12 +1691,25 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+const EXCLUDED_SOURCE_DIRECTORY_SEGMENTS = new Set([
+	".git",
+	".worktree",
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+]);
+
 // `.agents`/`.apifuse` stay IN scope on purpose: managed content there is
 // markdown/JSON (never scannable), while a planted `.ts`/`.sh` under those
 // directories must not become a scan-exempt hiding place for secrets, raw
-// fetch, or vendor imports.
+// fetch, or vendor imports. Nested dependency/build output directories under
+// them use the same segment exclusions; `.worktree` is excluded because task
+// worktrees are duplicate repository checkouts, not provider source.
 function shouldScanSourceDirectory(relativePath: string): boolean {
-	return ![".git", "node_modules", "dist", "build", "coverage"].includes(relativePath);
+	return relativePath
+		.split("/")
+		.every((segment) => !EXCLUDED_SOURCE_DIRECTORY_SEGMENTS.has(segment));
 }
 
 function isExcludedTestSource(relativePath: string): boolean {

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
-export { createBypassProviderCache, createProviderCache, type ProviderCacheOptions, resetProviderCacheForTests, } from "./runtime/cache.js";
+export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, resetProviderCacheForTests, } from "./runtime/cache.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";

package/dist/index.js

@@ -15,7 +15,7 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
-export { createBypassProviderCache, createProviderCache, resetProviderCacheForTests, } from "./runtime/cache.js";
+export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, resetProviderCacheForTests, } from "./runtime/cache.js";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";

package/dist/runtime/cache.d.ts

@@ -5,6 +5,7 @@ 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;
 export declare function createBypassProviderCache(options: Pick<ProviderCacheOptions, "providerId">): ProviderCache;
 export declare function resetProviderCacheForTests(): void;

package/dist/runtime/cache.js

@@ -1,9 +1,12 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.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 +21,7 @@ const SECRET_FIELD_NAMES = new Set([
     "refresh_token",
 ]);
 const sharedBackends = new Map();
+let warnedAboutUnpepperedSecretKeys = false;
 function backendKey(redisUrl) {
     return redisUrl ?? "memory";
 }
@@ -55,20 +59,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;
+    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 };
+    }
+    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,10 +279,13 @@ async function withRedisFallback(operation) {
 }
 export function createProviderCache(options) {
     const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+    const configuredPepper = process.env[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 secretScopedKeys = new Set();
     function record(meta) {
         events.push(meta);
     }
@@ -266,8 +410,11 @@ export function createProviderCache(options) {
     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);
@@ -312,19 +459,25 @@ 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),
             };
         },
     };
 }
 export function createBypassProviderCache(options) {
+    const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+    const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
     const events = [];
+    const secretScopedKeys = new Set();
     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) {
             return null;
@@ -352,7 +505,7 @@ 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),
             };
         },
@@ -365,4 +518,5 @@ export function resetProviderCacheForTests() {
         backend.redis?.disconnect();
     }
     sharedBackends.clear();
+    warnedAboutUnpepperedSecretKeys = false;
 }

package/dist/types.d.ts

@@ -1332,9 +1332,9 @@ export interface NativeProviderConfig {
 }
 export interface ProviderCacheKeyOptions {
     /**
-     * Additional field names to omit from stable key material. The SDK always
-     * omits known secret-bearing names such as serviceKey, authorization,
-     * cookie, token, password, and secret.
+     * Additional field names whose values are hashed in stable key material. The
+     * SDK always hashes values under known secret-bearing names such as serviceKey,
+     * authorization, cookie, token, password, and secret.
      */
     redactFields?: string[];
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.24",
+	"version": "2.2.0-beta.25",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/index.ts

@@ -52,6 +52,7 @@ export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
 export {
+	APIFUSE__CACHE__KEY_PEPPER_ENV,
 	createBypassProviderCache,
 	createProviderCache,
 	type ProviderCacheOptions,

package/src/runtime/cache.ts

@@ -1,6 +1,7 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
 import type {
 	ProviderCache,
 	ProviderCacheGetOrSetOptions,
@@ -43,9 +44,12 @@ export type ProviderCacheOptions = {
 	now?: () => number;
 };
 
+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",
@@ -61,6 +65,7 @@ const SECRET_FIELD_NAMES = new Set([
 ]);
 
 const sharedBackends = new Map<string, SharedCacheBackend>();
+let warnedAboutUnpepperedSecretKeys = false;
 
 function backendKey(redisUrl: string | undefined): string {
 	return redisUrl ?? "memory";
@@ -107,19 +112,178 @@ function shouldRedactField(name: string, extra: Set<string>): boolean {
 	);
 }
 
-function normalizeKeyPart(value: unknown, extra: Set<string>): unknown {
+type NormalizedKeyPart = {
+	value: unknown;
+	secretScoped: boolean;
+};
+
+function unsupportedSecretValue(path: string, reason: string): never {
+	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: unknown,
+	reportedPath: string,
+	ancestors = new Set<object>(),
+): void {
+	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: unknown): boolean {
+	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: unknown): unknown {
+	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 as Record<string, unknown>).map(([key, entry]) => [
+			key,
+			tagSecretValue(entry),
+		]),
+	];
+}
+
+function serializeSecretValue(value: unknown): string {
+	if (!containsUndefined(value)) return JSON.stringify([value]);
+	return `undefined-v1:${JSON.stringify(tagSecretValue(value))}`;
+}
+
+function warnAboutUnpepperedSecretKey(): void {
+	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: unknown,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
 	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: Record<string, unknown> = {};
+		const normalized: Record<string, unknown> = 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: unknown,
+	fieldName: string,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
+	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: ProviderCacheLookupMeta[],
+	secretScopedKeys: Set<string>,
+): string[] {
+	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: unknown): string {
@@ -198,10 +362,13 @@ async function withRedisFallback<T>(operation: () => Promise<T>): Promise<T | un
 
 export function createProviderCache(options: ProviderCacheOptions): ProviderCache {
 	const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const 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: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	function record(meta: ProviderCacheLookupMeta): void {
 		events.push(meta);
@@ -353,8 +520,10 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			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<T = unknown>(key: string): Promise<ProviderCacheResult<T> | null> {
@@ -413,7 +582,7 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 			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),
 			};
 		},
@@ -423,13 +592,18 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const events: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			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<T = unknown>(_key: string): Promise<ProviderCacheResult<T> | null> {
@@ -464,7 +638,7 @@ export function createBypassProviderCache(
 			return {
 				hit: false,
 				stale: false,
-				keys: Array.from(new Set(events.map((event) => event.key))),
+				keys: metadataKeys(events, secretScopedKeys),
 				source: sourceSummary(events),
 			};
 		},
@@ -478,4 +652,5 @@ export function resetProviderCacheForTests(): void {
 		backend.redis?.disconnect();
 	}
 	sharedBackends.clear();
+	warnedAboutUnpepperedSecretKeys = false;
 }

package/src/types.ts

@@ -1615,9 +1615,9 @@ export interface NativeProviderConfig {
 
 export interface ProviderCacheKeyOptions {
 	/**
-	 * Additional field names to omit from stable key material. The SDK always
-	 * omits known secret-bearing names such as serviceKey, authorization,
-	 * cookie, token, password, and secret.
+	 * Additional field names whose values are hashed in stable key material. The
+	 * SDK always hashes values under known secret-bearing names such as serviceKey,
+	 * authorization, cookie, token, password, and secret.
 	 */
 	redactFields?: string[];
 }