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

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/runtime/resolver-vendors/bindings.d.ts

@@ -1,8 +1,48 @@
 import type { ProviderChallenge } from "../../types.js";
 import type { ResolverIssuingIdentity } from "./types.js";
 export declare const RESOLVER_CHALLENGE_BINDINGS: {
-    readonly aws_waf: "portable";
-    readonly cloudflare_interstitial: "identity_scoped";
+    readonly turnstile: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly recaptcha_v2: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly recaptcha_v3: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly hcaptcha: {
+        readonly cacheable: false;
+        readonly identityBinding: "none";
+        readonly directCacheable: false;
+    };
+    readonly cloudflare_interstitial: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: true;
+    };
+    readonly aws_waf: {
+        readonly cacheable: true;
+        readonly identityBinding: "portable";
+        readonly directCacheable: true;
+    };
+    readonly akamai_sec_cpt: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
+    readonly akamai_sensor: {
+        readonly cacheable: true;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
 };
+export declare function resolverChallengeIsCacheable(challenge: ProviderChallenge): boolean;
+export declare function resolverChallengeAllowsDirectCache(challenge: ProviderChallenge): boolean;
 export declare function resolverChallengeIsIdentityScoped(challenge: ProviderChallenge): boolean;
 export declare function resolverChallengeIssuingIdentity(challenge: ProviderChallenge, identity: ResolverIssuingIdentity): ResolverIssuingIdentity;

package/dist/runtime/resolver-vendors/bindings.js

@@ -1,14 +1,39 @@
+// An IP-bound artifact minted without any recorded egress identity is unsafe to
+// share. The Akamai kinds therefore reject direct caching, while Cloudflare
+// keeps its pre-existing direct-cache behavior pending measurement.
 export const RESOLVER_CHALLENGE_BINDINGS = {
-    aws_waf: "portable",
-    cloudflare_interstitial: "identity_scoped",
+    turnstile: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v2: { cacheable: false, identityBinding: "none", directCacheable: false },
+    recaptcha_v3: { cacheable: false, identityBinding: "none", directCacheable: false },
+    hcaptcha: { cacheable: false, identityBinding: "none", directCacheable: false },
+    cloudflare_interstitial: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: true,
+    },
+    aws_waf: { cacheable: true, identityBinding: "portable", directCacheable: true },
+    akamai_sec_cpt: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
+    akamai_sensor: {
+        cacheable: true,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
 };
+export function resolverChallengeIsCacheable(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;
+}
+export function resolverChallengeAllowsDirectCache(challenge) {
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].directCacheable;
+}
 export function resolverChallengeIsIdentityScoped(challenge) {
-    return (RESOLVER_CHALLENGE_BINDINGS[challenge.kind] ===
-        "identity_scoped");
+    return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "identity_scoped";
 }
 export function resolverChallengeIssuingIdentity(challenge, identity) {
-    const binding = RESOLVER_CHALLENGE_BINDINGS[challenge.kind];
-    if (binding === "portable") {
+    if (RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "portable") {
         return { userAgent: identity.userAgent };
     }
     return identity;

package/dist/runtime/resolver-vendors/browser.d.ts

@@ -10,15 +10,11 @@ export interface BrowserResolverVendorOptions {
     readonly allowedHosts: readonly string[];
     readonly createClient?: BrowserClientFactory;
 }
-export type BrowserResolverSolution = Extract<ChallengeSolution, {
-    readonly form: "cookies";
-}> & {
-    /** Unix seconds from the cookie that proved the challenge cleared. */
-    readonly expires?: number;
-};
 export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
     readonly id: "browser";
-    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<BrowserResolverSolution>;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
+        readonly form: "cookies";
+    }>>;
 }
 export declare function createBrowserResolverVendorAdapter(options: BrowserResolverVendorOptions): BrowserResolverVendorAdapter;
 export {};

package/dist/runtime/resolver-vendors/browser.js

@@ -1,6 +1,7 @@
-import { isProviderError, ProviderError } from "../../errors.js";
+import { isProviderError } from "../../errors.js";
 import { createBrowserClient } from "../browser.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
+import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import { ResolverVendorUnavailableError, } from "./types.js";
 const BROWSER_VENDOR_ID = "browser";
 const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
@@ -94,32 +95,16 @@ async function abortableDelay(ms, signal) {
 function isSupportedKind(kind) {
     return Object.hasOwn(SUCCESS_COOKIE_NAMES, kind);
 }
-function normalizedHostname(hostname) {
-    return hostname.trim().toLowerCase().replace(/\.$/, "");
-}
-function assertChallengeHostAllowed(pageUrl, allowedHosts) {
-    const challengeHost = normalizedHostname(new URL(pageUrl).hostname);
-    const isAllowed = allowedHosts.some((host) => {
-        const declaredHost = normalizedHostname(host);
-        return declaredHost.length > 0 && !declaredHost.includes("*") && declaredHost === challengeHost;
-    });
-    if (isAllowed)
-        return;
-    throw new ProviderError(`Resolver challenge host "${challengeHost}" is not declared`, {
-        code: "RESOLVER_HOST_NOT_ALLOWED",
-        fix: "Add the exact challenge hostname to the provider's allowedHosts declaration.",
-    });
-}
 function cookieDomainSpecificity(cookie) {
-    return normalizedHostname(cookie.domain.replace(/^\./, "")).length;
+    return normalizedResolverHostname(cookie.domain.replace(/^\./, "")).length;
 }
 function isHostOnlyCookieFor(cookie, hostname) {
     return (!cookie.domain.startsWith(".") &&
-        normalizedHostname(cookie.domain) === normalizedHostname(hostname));
+        normalizedResolverHostname(cookie.domain) === normalizedResolverHostname(hostname));
 }
 function cookieAppliesToUrl(cookie, url) {
-    const cookieDomain = normalizedHostname(cookie.domain.replace(/^\./, ""));
-    const requestHostname = normalizedHostname(url.hostname);
+    const cookieDomain = normalizedResolverHostname(cookie.domain.replace(/^\./, ""));
+    const requestHostname = normalizedResolverHostname(url.hostname);
     const domainMatches = cookieDomain.length > 0 &&
         (requestHostname === cookieDomain ||
             (cookie.domain.startsWith(".") && requestHostname.endsWith(`.${cookieDomain}`)));
@@ -226,7 +211,7 @@ export function createBrowserResolverVendorAdapter(options) {
             if (!isSupportedKind(challenge.kind)) {
                 throw new TypeError(`Browser resolver does not support ${challenge.kind}`);
             }
-            assertChallengeHostAllowed(challenge.pageUrl, options.allowedHosts);
+            assertResolverHostAllowed(challenge.pageUrl, options.allowedHosts);
             const challengeKind = challenge.kind;
             callerSignal.throwIfAborted();
             const solveController = new AbortController();

package/dist/runtime/resolver-vendors/hosts.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizedResolverHostname(hostname: string): string;
+export declare function assertResolverHostAllowed(targetUrl: string, allowedHosts: readonly string[]): void;

package/dist/runtime/resolver-vendors/hosts.js

@@ -0,0 +1,33 @@
+import { ProviderError } from "../../errors.js";
+export function normalizedResolverHostname(hostname) {
+    return hostname.trim().toLowerCase().replace(/\.$/, "");
+}
+export function assertResolverHostAllowed(targetUrl, allowedHosts) {
+    let targetUrlObject;
+    try {
+        targetUrlObject = new URL(targetUrl);
+    }
+    catch {
+        throw new ProviderError("Resolver target URL is invalid", {
+            code: "RESOLVER_HOST_NOT_ALLOWED",
+            fix: "Use a valid URL whose exact hostname appears in the provider's allowedHosts declaration.",
+        });
+    }
+    if (targetUrlObject.protocol !== "http:" && targetUrlObject.protocol !== "https:") {
+        throw new ProviderError(`Resolver target URL scheme "${targetUrlObject.protocol}" is not allowed`, {
+            code: "RESOLVER_HOST_NOT_ALLOWED",
+            fix: "Use an http or https URL whose exact hostname appears in the provider's allowedHosts declaration.",
+        });
+    }
+    const targetHost = normalizedResolverHostname(targetUrlObject.hostname);
+    const isAllowed = allowedHosts.some((host) => {
+        const declaredHost = normalizedResolverHostname(host);
+        return declaredHost.length > 0 && !declaredHost.includes("*") && declaredHost === targetHost;
+    });
+    if (isAllowed)
+        return;
+    throw new ProviderError(`Resolver target host "${targetHost}" is not declared`, {
+        code: "RESOLVER_HOST_NOT_ALLOWED",
+        fix: "Add the exact target hostname to the provider's allowedHosts declaration.",
+    });
+}

package/dist/runtime/resolver-vendors/twocaptcha.d.ts

@@ -0,0 +1,23 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
+export interface TwoCaptchaResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+    readonly allowedHosts: readonly string[];
+    readonly fetchImpl?: typeof fetch;
+    readonly baseUrl?: string;
+    /** Test-only clock override; supplying it disables the real-time deadline timer. */
+    readonly now?: () => number;
+    /** Test-only delay override used with `now` to exercise polling without sleeping. */
+    readonly delay?: Delay;
+}
+export interface TwoCaptchaResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "2captcha";
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal): Promise<Extract<ChallengeSolution, {
+        readonly form: "token";
+    }>>;
+}
+export declare function createTwoCaptchaResolverVendorAdapter(options: TwoCaptchaResolverVendorOptions): TwoCaptchaResolverVendorAdapter;
+export {};