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

package/dist/runtime/egress-lease.js

@@ -0,0 +1,236 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { SDKError } from "../errors.js";
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export const ENGINE_CEREMONY_EGRESS_LEASE = Symbol.for("@apifuse/provider-sdk/engine-ceremony-egress-lease");
+const HANDLE_VERSION = 1;
+const HANDLE_MAX_BYTES = 16_384;
+const AEAD_NONCE_BYTES = 12;
+const AEAD_TAG_BYTES = 16;
+const AEAD_ALGORITHM = "aes-256-gcm";
+const AEAD_KEY_DOMAIN = "apifuse:ceremony-egress-lease:v1\0";
+const LEASE_KEY_MIN_BYTES = 32;
+/** The caller presented a handle this engine cannot verify for this ceremony (409). */
+function invalidLease() {
+    throw new SDKError("The engine ceremony egress lease is invalid", {
+        code: "EGRESS_LEASE_INVALID",
+        fix: "Restart the authentication ceremony to obtain a new engine-owned egress lease.",
+    });
+}
+/** The engine violated its own binding invariant (500); never attributable to the caller. */
+function bindingFault(message) {
+    throw new SDKError(message, {
+        code: "EGRESS_LEASE_BINDING_INVALID",
+        fix: "This is an SDK or provider-runtime fault; the ceremony lease cannot bind the selected egress.",
+    });
+}
+function encryptionKey(key) {
+    return createHash("sha256").update(AEAD_KEY_DOMAIN, "utf8").update(key, "utf8").digest();
+}
+/** Fixed field order and JSON.stringify's compact form are the canonical AAD encoding. */
+function scopeAad(scope) {
+    return Buffer.from(JSON.stringify({
+        version: HANDLE_VERSION,
+        tenantId: scope.tenantId,
+        providerId: scope.providerId,
+        flowId: scope.flowId,
+        affinityKey: scope.affinityKey,
+    }), "utf8");
+}
+function encodeHandle(payload, key, scope) {
+    const nonce = randomBytes(AEAD_NONCE_BYTES);
+    const cipher = createCipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+        authTagLength: AEAD_TAG_BYTES,
+    });
+    cipher.setAAD(scopeAad(scope));
+    const ciphertext = Buffer.concat([
+        cipher.update(JSON.stringify(payload), "utf8"),
+        cipher.final(),
+    ]);
+    return [
+        `v${HANDLE_VERSION}`,
+        nonce.toString("base64url"),
+        ciphertext.toString("base64url"),
+        cipher.getAuthTag().toString("base64url"),
+    ].join(".");
+}
+function isFiniteInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isPositiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function decodeHandle(handle, key, scope) {
+    if (Buffer.byteLength(handle, "utf8") > HANDLE_MAX_BYTES)
+        return invalidLease();
+    const parts = handle.split(".");
+    if (parts.length !== 4 ||
+        parts[0] !== `v${HANDLE_VERSION}` ||
+        parts.slice(1).some((part) => !/^[A-Za-z0-9_-]+$/u.test(part))) {
+        return invalidLease();
+    }
+    let parsed;
+    try {
+        const nonce = Buffer.from(parts[1], "base64url");
+        const ciphertext = Buffer.from(parts[2], "base64url");
+        const tag = Buffer.from(parts[3], "base64url");
+        if (nonce.byteLength !== AEAD_NONCE_BYTES ||
+            tag.byteLength !== AEAD_TAG_BYTES ||
+            ciphertext.byteLength === 0) {
+            return invalidLease();
+        }
+        const decipher = createDecipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+            authTagLength: AEAD_TAG_BYTES,
+        });
+        decipher.setAAD(scopeAad(scope));
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        parsed = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        return invalidLease();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return invalidLease();
+    const candidate = parsed;
+    if (candidate.version !== HANDLE_VERSION ||
+        (candidate.vendor !== "smartproxy" && candidate.vendor !== "nodemaven") ||
+        typeof candidate.proxyUrl !== "string" ||
+        !candidate.proxyUrl ||
+        !isFiniteInteger(candidate.poolIndex) ||
+        typeof candidate.affinityKey !== "string" ||
+        !candidate.affinityKey ||
+        !isFiniteInteger(candidate.refreshEpoch) ||
+        typeof candidate.tenantId !== "string" ||
+        !candidate.tenantId ||
+        typeof candidate.providerId !== "string" ||
+        !candidate.providerId ||
+        typeof candidate.flowId !== "string" ||
+        !candidate.flowId ||
+        !isFiniteInteger(candidate.mintedAtMs) ||
+        !isFiniteInteger(candidate.expiresAtMs) ||
+        candidate.expiresAtMs <= candidate.mintedAtMs ||
+        !isPositiveFinite(candidate.lifetimeMinutes)) {
+        return invalidLease();
+    }
+    try {
+        const proxy = new URL(candidate.proxyUrl);
+        if (proxy.protocol !== "http:" && proxy.protocol !== "socks5:")
+            return invalidLease();
+    }
+    catch {
+        return invalidLease();
+    }
+    return candidate;
+}
+function bindingOf(payload) {
+    return {
+        vendor: payload.vendor,
+        proxyUrl: payload.proxyUrl,
+        poolIndex: payload.poolIndex,
+        affinityKey: payload.affinityKey,
+        refreshEpoch: payload.refreshEpoch,
+        lifetimeMinutes: payload.lifetimeMinutes,
+    };
+}
+export function createCeremonyEgressLeaseRuntime(options) {
+    const environment = options.environment ?? process.env;
+    const now = options.now ?? Date.now;
+    if (typeof options.tenantId !== "string" || !options.tenantId.trim()) {
+        throw new SDKError("A tenant is required for an engine ceremony egress lease", {
+            code: "EGRESS_LEASE_INVALID",
+            fix: "Restart the authentication ceremony with its tenant identity.",
+        });
+    }
+    const scope = {
+        tenantId: options.tenantId,
+        providerId: options.providerId,
+        flowId: options.flowId,
+        affinityKey: options.affinityKey,
+    };
+    const key = readDiagnosticEnv(APIFUSE__ENGINE__CEREMONY_LEASE_KEY, environment)?.trim();
+    if (!key) {
+        throw new SDKError("The engine ceremony egress lease key is not configured", {
+            code: "EGRESS_LEASE_KEY_MISSING",
+            fix: `Configure ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} in the engine host.`,
+        });
+    }
+    // The key is the whole authenticity boundary of a handle (a verified handle's proxyUrl
+    // becomes the ceremony egress), so the documented minimum is enforced, not advisory.
+    if (Buffer.byteLength(key, "utf8") < LEASE_KEY_MIN_BYTES) {
+        throw new SDKError(`The engine ceremony egress lease key is shorter than ${LEASE_KEY_MIN_BYTES} bytes`, {
+            code: "EGRESS_LEASE_KEY_WEAK",
+            fix: `Set ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} to at least ${LEASE_KEY_MIN_BYTES} random bytes (for example \`openssl rand -base64 32\`).`,
+        });
+    }
+    let payload;
+    let currentHandle;
+    let generation = 0;
+    const dropBinding = () => {
+        if (!payload)
+            return false;
+        payload = undefined;
+        currentHandle = undefined;
+        generation += 1;
+        return true;
+    };
+    const dropExpiredBinding = () => payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
+    if (options.handle !== undefined) {
+        options.onHandle?.(options.handle);
+        // Scope mismatch fails GCM authentication because scope is AAD; there is
+        // deliberately no post-decrypt scope comparison fallback.
+        payload = decodeHandle(options.handle, key, scope);
+        currentHandle = options.handle;
+        // An expired but authentic handle is not a fault: the ceremony continues on a
+        // freshly selected endpoint and the next turn receives the new handle.
+        dropExpiredBinding();
+    }
+    return {
+        get binding() {
+            return payload ? bindingOf(payload) : undefined;
+        },
+        dropExpiredBinding,
+        dropBinding,
+        get generation() {
+            return generation;
+        },
+        bind(binding) {
+            if (payload) {
+                // The stealth runtime reuses the bound endpoint while a binding exists and
+                // never rebinds it; a second bind is an engine invariant break.
+                return bindingFault("The ceremony egress lease is already bound");
+            }
+            if (binding.affinityKey !== options.affinityKey ||
+                !binding.proxyUrl ||
+                (binding.vendor !== "smartproxy" && binding.vendor !== "nodemaven") ||
+                !isFiniteInteger(binding.poolIndex) ||
+                !isPositiveFinite(binding.lifetimeMinutes)) {
+                return bindingFault("The selected egress cannot be bound to the ceremony lease");
+            }
+            const mintedAtMs = now();
+            payload = {
+                version: HANDLE_VERSION,
+                tenantId: scope.tenantId,
+                providerId: options.providerId,
+                flowId: options.flowId,
+                ...binding,
+                mintedAtMs,
+                expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
+            };
+            currentHandle = encodeHandle(payload, key, scope);
+            options.onHandle?.(currentHandle);
+        },
+        handle() {
+            return currentHandle;
+        },
+    };
+}

package/dist/runtime/env.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { isEngineOwnedEnvName } from "../engine.js";
 /**
  * A mixed-case spelling of an engine-owned name is an alias: on Windows it resolves to the
@@ -16,7 +17,7 @@ export function createEnvContext(allowedKeys) {
             if (isEngineOwnedEnvAlias(key)) {
                 return undefined;
             }
-            return process.env[key];
+            return readDiagnosticEnv(key);
         },
     };
 }

package/dist/runtime/http.js

@@ -498,6 +498,7 @@ async function resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffs
         // supported here, so a socks5 policy fails loudly rather than downgrading.
         transportProtocols: ["http"],
         telemetry: clientOptions.telemetry,
+        engineCredentials: clientOptions.engineCredentials,
     });
     if (resolvedProxy.shouldWarn) {
         warn("[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.");

package/dist/runtime/instrumentation.js

@@ -1,3 +1,4 @@
+import { registerDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
 import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
@@ -381,6 +382,7 @@ function wrapStealthRedirects(redirects, trace) {
         run(...args) {
             const diagnosticArgs = [args[0].url, args[0]];
             const diagnostics = snapshotRequestDiagnostics("stealth", "fetch", diagnosticArgs);
+            registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
             let result;
             try {
                 result = redirects.run(...args);
@@ -511,6 +513,7 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
                     return Reflect.apply(value, namespaceTarget, args);
                 }
                 const requestDiagnostics = snapshotRequestDiagnostics(namespace, methodName, args);
+                registerDiagnosticSensitiveValues(trace, requestDiagnostics.sensitiveValues);
                 // Invoke first and decide by the RETURN VALUE. `runSpan` always
                 // returns a Promise, so unconditionally span-wrapping every member
                 // silently rewrote synchronous contracts: `ctx.state.namespace()`

package/dist/runtime/ocr.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
 import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
@@ -55,7 +56,7 @@ export function createUnsupportedOcrClient(reason) {
     });
 }
 function normalizedEnvValue(env, key) {
-    const value = env[key]?.trim();
+    const value = readDiagnosticEnv(key, env)?.trim();
     return value ? value : undefined;
 }
 export function createOcrClientFromEnv(config, env = process.env) {

package/dist/runtime/otlp.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { AsyncResource } from "node:async_hooks";
 export const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
 export const OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT";
@@ -118,12 +119,12 @@ export function resolveOTLPExportOptions(explicit, env = process.env) {
         { source: EXPLICIT_ENDPOINT_SOURCE, value: explicit.endpoint, appendPath: false },
         {
             source: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
-            value: env[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT],
+            value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, env),
             appendPath: false,
         },
         {
             source: OTEL_EXPORTER_OTLP_ENDPOINT,
-            value: env[OTEL_EXPORTER_OTLP_ENDPOINT],
+            value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_ENDPOINT, env),
             appendPath: true,
         },
     ];
@@ -137,9 +138,9 @@ export function resolveOTLPExportOptions(explicit, env = process.env) {
         return { status: "invalid", source: candidate.source, reason: parsed.reason };
     }
     const endpoint = candidate.appendPath ? appendTracesPath(parsed.url) : candidate.value;
-    const tracesHeaders = presentValue(env[OTEL_EXPORTER_OTLP_TRACES_HEADERS]);
+    const tracesHeaders = presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_HEADERS, env));
     const headersSource = tracesHeaders !== undefined ? OTEL_EXPORTER_OTLP_TRACES_HEADERS : OTEL_EXPORTER_OTLP_HEADERS;
-    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(env[OTEL_EXPORTER_OTLP_HEADERS]));
+    const envHeaders = parseHeaderList(tracesHeaders ?? presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_HEADERS, env)));
     if (!headersAreSendable(envHeaders)) {
         return { status: "invalid", source: headersSource, reason: INVALID_HEADERS };
     }

package/dist/runtime/proxy-nodemaven.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, randomBytes } from "node:crypto";
 export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
 export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
@@ -25,10 +26,10 @@ export function hasNodemavenCredentials() {
     return Boolean(readNodemavenUsername() && readNodemavenPassword());
 }
 function readNodemavenUsername() {
-    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+    return readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)?.trim() || undefined;
 }
 function readNodemavenPassword() {
-    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+    return readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)?.trim() || undefined;
 }
 function resolveNodemavenFilter(value) {
     const raw = value?.trim().toLowerCase();

package/dist/runtime/proxy-retry-policy.d.ts

@@ -21,7 +21,10 @@ export declare function normalizeProxyTransportRetryOptions(retry: RequestOption
     label?: RetryPolicyLabel;
 }): NormalizedProxyTransportRetryOptions | undefined;
 export declare function validateUnsafeProxyTransportRetryMethods(options: NormalizedProxyTransportRetryOptions, label?: RetryPolicyLabel): void;
-export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions, request?: {
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string | readonly string[] | undefined>>;
+}): boolean;
 export declare function shouldRetryProxyTransportError(error: unknown, options: NormalizedProxyTransportRetryOptions): boolean;
 export declare function shouldRetryProxyTransportAttempt(input: {
     error: unknown;

package/dist/runtime/proxy-retry-policy.js

@@ -1,5 +1,6 @@
 import { ProviderError, TransportError } from "../errors.js";
 import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types.js";
+import { isSensitiveKey } from "./request-options.js";
 export const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
 export const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES = [
     "transport_network_error",
@@ -250,10 +251,18 @@ export function validateUnsafeProxyTransportRetryMethods(options, label = "Proxy
         return;
     throw new ProviderError(`${label} retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
 }
-export function isProxyTransportRetryMethod(method, options) {
-    return options.methods
+export function isProxyTransportRetryMethod(method, options, request) {
+    const methodAllowed = options.methods
         .map((allowedMethod) => allowedMethod.toUpperCase())
         .includes(method.toUpperCase());
+    if (!methodAllowed || request === undefined)
+        return methodAllowed;
+    if (request.body !== undefined)
+        return false;
+    return !Object.keys(request.headers ?? {}).some((name) => {
+        const normalized = name.toLowerCase();
+        return normalized === "cookie" || normalized === "proxy-authorization" || isSensitiveKey(name);
+    });
 }
 export function shouldRetryProxyTransportError(error, options) {
     const code = retryErrorCode(error);

package/dist/runtime/request-options.d.ts

@@ -51,6 +51,13 @@ export declare function redactUrlQueryParams(url: string, sensitiveParamNames: r
  * separate, structurally redacted URL for diagnostics and observability.
  */
 export declare function serializeRequestUrl(url: string, params?: RequestParams, sensitiveParams?: Record<string, string>): SerializedRequestUrl;
+export declare function normalizePercentEscapes(value: string): string;
+export type SensitiveValueVariant = {
+    value: string;
+    requiresTokenBoundary: boolean;
+    caseInsensitive: boolean;
+};
+export declare function allSensitiveValueVariants(sensitiveValues: readonly string[]): SensitiveValueVariant[];
 /** Scrubs raw and URL-encoded secret values from diagnostic text. */
 export declare function redactSensitiveText(text: string, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): string;
 /**

package/dist/runtime/request-options.js

@@ -108,13 +108,33 @@ export function serializeRequestUrl(url, params, sensitiveParams) {
         sensitiveValues: [...sensitiveValues],
     };
 }
-const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 4;
-function normalizePercentEscapes(value) {
+const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 8;
+export function normalizePercentEscapes(value) {
     return value.replace(/%[\da-f]{2}/gi, (percentEscape) => percentEscape.toUpperCase());
 }
 function sensitiveValueVariants(value) {
     if (!value || value === REDACTED_QUERY_VALUE)
         return [];
+    // Owner-visible policy: short credentials are literal, case-sensitive tokens only.
+    // Encoded short needles collide with benign cursors and ordinary diagnostic text.
+    if (value.length < 8)
+        return [value];
+    // These ASCII characters are identical under NFC, JSON, URI-component and
+    // form encoding. Avoid constructing those identical variants for common tokens.
+    if (/^[A-Za-z0-9._*-]+$/.test(value)) {
+        const base64 = Buffer.from(value, "utf8").toString("base64");
+        const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+        return [
+            ...new Set([
+                value,
+                base64,
+                base64.replace(/=+$/, ""),
+                base64Url,
+                base64Url.replace(/=+$/, ""),
+            ]),
+        ];
+    }
+    const normalized = value.normalize("NFC");
     const formEncoded = new URLSearchParams({ value }).toString().slice("value=".length);
     let componentEncoded;
     try {
@@ -125,12 +145,31 @@ function sensitiveValueVariants(value) {
         // still safe to scrub, and URLSearchParams supplies its well-formed form.
         componentEncoded = value;
     }
-    return [...new Set([value, componentEncoded, formEncoded].map(normalizePercentEscapes))];
-}
-function allSensitiveValueVariants(sensitiveValues) {
+    const base64 = Buffer.from(value, "utf8").toString("base64");
+    const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+    const jsonEscaped = JSON.stringify(value).slice(1, -1);
+    return [
+        ...new Set([
+            value,
+            normalized,
+            componentEncoded,
+            formEncoded,
+            jsonEscaped,
+            base64,
+            base64.replace(/=+$/, ""),
+            base64Url,
+            base64Url.replace(/=+$/, ""),
+        ].map(normalizePercentEscapes)),
+    ];
+}
+export function allSensitiveValueVariants(sensitiveValues) {
     const variants = new Map();
     for (const sensitiveValue of sensitiveValues) {
         const requiresTokenBoundary = sensitiveValue.length < MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH;
+        // Long values are unlikely to be ordinary prose, so case folding is worth
+        // the extra over-redaction protection. Values of 4-7 characters remain
+        // case-sensitive because they commonly occur as words and identifiers.
+        const caseInsensitive = sensitiveValue.length >= 8;
         for (const value of sensitiveValueVariants(sensitiveValue)) {
             const existing = variants.get(value);
             variants.set(value, {
@@ -138,6 +177,7 @@ function allSensitiveValueVariants(sensitiveValues) {
                 requiresTokenBoundary: existing
                     ? existing.requiresTokenBoundary && requiresTokenBoundary
                     : requiresTokenBoundary,
+                caseInsensitive: existing ? existing.caseInsensitive || caseInsensitive : caseInsensitive,
             });
         }
     }
@@ -147,24 +187,24 @@ function isTokenCharacter(value) {
     return value !== undefined && /[\p{L}\p{N}]/u.test(value);
 }
 function replaceSensitiveVariant(text, variant) {
-    const pattern = variant.value.replace(/%([\da-f]{2})|[.*+?^${}()|[\]\\]/gi, (match, hex) => {
-        if (hex) {
-            return `%${[...String(hex)]
-                .map((character) => /[a-f]/i.test(character)
-                ? `[${character.toLowerCase()}${character.toUpperCase()}]`
-                : character)
-                .join("")}`;
-        }
-        return `\\${match}`;
-    });
-    return text.replace(new RegExp(pattern, "gu"), (match, offset, source) => {
-        const end = offset + match.length;
+    const normalized = normalizePercentEscapes(text);
+    const comparable = variant.caseInsensitive ? normalized.toLowerCase() : text;
+    const needle = variant.caseInsensitive ? variant.value.toLowerCase() : variant.value;
+    let cursor = 0;
+    let output = "";
+    for (let index = comparable.indexOf(needle); index !== -1; index = comparable.indexOf(needle, index + 1)) {
+        const end = index + needle.length;
         if (variant.requiresTokenBoundary &&
-            (isTokenCharacter(source[offset - 1]) || isTokenCharacter(source[end]))) {
-            return match;
-        }
-        return REDACTED_QUERY_VALUE;
-    });
+            (isTokenCharacter(comparable[index - 1]) || isTokenCharacter(comparable[end])))
+            continue;
+        // Unicode folding can change offsets; suppress the field instead of slicing a secret.
+        if (comparable.length !== text.length)
+            return REDACTED_QUERY_VALUE;
+        output += text.slice(cursor, index) + REDACTED_QUERY_VALUE;
+        cursor = end;
+        index = end - 1;
+    }
+    return cursor ? output + text.slice(cursor) : text;
 }
 /** Scrubs raw and URL-encoded secret values from diagnostic text. */
 export function redactSensitiveText(text, sensitiveValues, requestUrl, redactedUrl) {

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

@@ -1,5 +1,6 @@
 import type { ProxyTelemetrySink } from "../config/loader.js";
 import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { ResolverTelemetryLogPayload } from "./resolver-telemetry.js";
 import type { Span, TraceContext } from "./trace.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 export type TelemetryKey = "proxy" | "resolver" | "http" | "stealth" | "native" | "browser" | "ocr" | "stt" | "cache" | "state" | "events";
@@ -21,17 +22,13 @@ export declare function tenantOpaqueKeys(value: string[]): TenantOpaqueKeys;
  * URLs, hostnames, free text, unknown values, and escape-hatch properties reduce to `never`.
  */
 export type GatewayIngestible<T> = 0 extends 1 & T ? never : T extends object ? keyof T extends never ? never : {
-    [K in keyof T]: 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [readonly (infer U)[]] ? 0 extends 1 & U ? never : unknown extends U ? never : [U] extends [
-        number | boolean | ClosedEnum<string> | GatewayIngestible<U>
-    ] ? T[K] : never : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>] ? T[K] : never : never;
+    [K in keyof T]: 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [readonly (infer U)[]] ? 0 extends 1 & U ? never : unknown extends U ? never : [U] extends [number | boolean | ClosedEnum<string> | GatewayIngestible<U>] ? T[K] : never : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>] ? T[K] : never : never;
 } : never;
 /** Compile-time projection for tenant-visible, identity-neutral metadata. */
 export type TenantNeutral<T> = 0 extends 1 & T ? never : T extends object ? {
-    [K in keyof T]: K extends `vendor${string}` | "provider" | "engine" | "model" | `${string}Host` ? never : 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [
-        string[] & {
-            readonly __tenantOpaqueCacheKeys: true;
-        }
-    ] ? K extends "keys" ? T[K] : never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>] ? T[K] : never : never;
+    [K in keyof T]: K extends `vendor${string}` | "provider" | "engine" | "model" | `${string}Host` ? never : 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [string[] & {
+        readonly __tenantOpaqueCacheKeys: true;
+    }] ? K extends "keys" ? T[K] : never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>] ? T[K] : never : never;
 } : never;
 export interface SpanIndex {
     readonly spans: readonly Span[];
@@ -46,7 +43,8 @@ export interface TelemetryContributor<Log extends object, Header extends object>
 }
 export type RequestTelemetryLogPayload = {
     proxy?: ProxyTelemetryLogPayload;
-} & Partial<Record<Exclude<TelemetryKey, "proxy">, object>>;
+    resolver?: ResolverTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy" | "resolver">, object>>;
 /**
  * Bounded structural defence in depth against casts and accidental free text.
  * Closed-enum brands are erased at runtime; the type-level guard is the contract,

package/dist/runtime/resolver-config.d.ts

@@ -1,6 +1,13 @@
+import type { ProviderChallengeKind } from "../types.js";
 export declare const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
 export declare const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
 export declare const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export declare const APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY = "APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY";
 export declare const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
 export declare const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
 export declare const DEFAULT_RESOLVER_TIMEOUT_MS = 180000;
+/**
+ * SBSD is solved on the provider's own admitted session, so the transport profile must be
+ * declared up front. Other kinds, including `akamai_sensor`, keep the profile optional.
+ */
+export declare function kindRequiresClientProfile(kind: ProviderChallengeKind): boolean;

package/dist/runtime/resolver-config.js

@@ -1,6 +1,14 @@
 export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
 export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
 export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export const APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY = "APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY";
 export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
 export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
 export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;
+/**
+ * SBSD is solved on the provider's own admitted session, so the transport profile must be
+ * declared up front. Other kinds, including `akamai_sensor`, keep the profile optional.
+ */
+export function kindRequiresClientProfile(kind) {
+    return kind === "akamai_sbsd";
+}

package/dist/runtime/resolver-public.d.ts

@@ -1 +1,3 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";
+export { type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryIdentitySource, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "./resolver-telemetry.js";
+export type { ResolverPaidUsageContext, ResolverVendorUnavailableReason, } from "./resolver-vendors/types.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

package/dist/runtime/resolver-shared.d.ts

@@ -1,5 +1,13 @@
 import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
 import type { TraceRecorder } from "./trace.js";
+import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
+type ResolverTelemetryBinding = (sink: ResolverTelemetrySink) => ResolverContext;
+/** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
+export declare function registerResolverTelemetryBinding(resolver: ResolverContext, bind: ResolverTelemetryBinding): void;
+/** Preserve reconstruction across SDK wrappers without capturing their current request sink. */
+export declare function inheritResolverTelemetryBinding(resolver: ResolverContext, wrapper: ResolverContext): void;
+/** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
+export declare function bindResolverTelemetry(resolver: ResolverContext, sink: ResolverTelemetrySink | undefined): ResolverContext;
 export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
 /**
  * Internal solve surface. The instrumentation layer threads its recorder as a
@@ -12,3 +20,4 @@ export type ResolverSolveWithRecorder = {
     solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
 };
 export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;
+export {};