@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.41

package/dist/define.js

@@ -1,22 +1,90 @@
 import ms from "ms";
+import { validateFailClosedOperationDeclaration, validateFailClosedProviderDeclaration, } from "./declaration-validation.js";
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
+import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
-import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
+import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
+import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, VALID_OPERATION_ERROR_STATUSES, } from "./types.js";
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"];
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
+const VALID_AUTH_MODES = [
+    "none",
+    "platform-managed",
+    "credentials",
+    "oauth2",
+    "oauth2_proxied",
+];
+const PROXIED_OAUTH_REQUIRED_FIELDS = [
+    "authorizeUrl",
+    "tokenUrl",
+    "customScheme",
+    "rewriteProfile",
+    "clientIdEnvKey",
+];
+const PROXIED_OAUTH_ALLOWED_FIELDS = new Set([
+    ...PROXIED_OAUTH_REQUIRED_FIELDS,
+    "pkce",
+    "authorizeParams",
+    "tokenParams",
+]);
+const PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS = new Set([
+    "client_id",
+    "response_type",
+    "state",
+    "code_challenge",
+    "code_challenge_method",
+]);
+const PROXIED_OAUTH_PROFILE_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PROXIED_OAUTH_ENV_KEY_REGEX = /^[A-Z][A-Z0-9_]*__[A-Z0-9_]+$/;
+const CUSTOM_SCHEME_REGEX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+$/;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"];
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"];
-const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"];
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
     "auth-flow",
     "connection",
 ];
+const VALID_PROVIDER_OCR_MODES = ["optional", "required"];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
+function exhaustiveLiteralArray() {
+    return (values, ..._missing) => values;
+}
+export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray()([
+    "browser",
+    "capsolver",
+    "capmonster",
+    "2captcha",
+    "custom",
+]);
+export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray()([
+    "turnstile",
+    "recaptcha_v2",
+    "recaptcha_v3",
+    "hcaptcha",
+    "cloudflare_interstitial",
+    "aws_waf",
+    "akamai_sec_cpt",
+    "akamai_sensor",
+]);
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (the deprecated `custom`/`decodo` values have no managed
+// adapter) impose no declaration requirement.
+const VENDOR_REQUIRED_SECRETS = {
+    smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+    nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
@@ -42,13 +110,357 @@ function parsePositiveMsDuration(value) {
         return undefined;
     return parsed;
 }
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation(operation) {
-    return operation;
+function splitAuthStartParameters(parameters) {
+    const parts = [];
+    let start = 0;
+    let round = 0;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (let index = 0; index < parameters.length; index++) {
+        const character = parameters[index];
+        const nextCharacter = parameters[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (character === "\\") {
+                escaped = true;
+            }
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && parameters.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && parameters.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            round++;
+        else if (character === ")")
+            round--;
+        else if (character === "[")
+            square++;
+        else if (character === "]")
+            square--;
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+        }
+        else if (character === "," && round === 0 && square === 0 && curly === 0) {
+            parts.push(parameters.slice(start, index));
+            start = index + 1;
+        }
+        if (round < 0 || square < 0 || curly < 0)
+            return undefined;
+    }
+    if (quote ||
+        blockComment ||
+        templateDepths.length > 0 ||
+        round !== 0 ||
+        square !== 0 ||
+        curly !== 0)
+        return undefined;
+    parts.push(parameters.slice(start));
+    return parts;
 }
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation(operation) {
-    return operation;
+function authStartParameterList(source) {
+    let index = 0;
+    while (index < source.length && /\s/.test(source[index] ?? ""))
+        index++;
+    if (index >= source.length)
+        return undefined;
+    let openIndex = -1;
+    let parenthesizedArrow = false;
+    let asyncMethodOrArrow = false;
+    const skipTrivia = () => {
+        while (index < source.length) {
+            if (/\s/.test(source[index] ?? "")) {
+                index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "/") {
+                index += 2;
+                while (index < source.length && source[index] !== "\n" && source[index] !== "\r")
+                    index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "*") {
+                const end = source.indexOf("*/", index + 2);
+                if (end < 0) {
+                    index = source.length;
+                    return;
+                }
+                index = end + 2;
+                continue;
+            }
+            return;
+        }
+    };
+    const initial = source.slice(index);
+    const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+    if (isAsync) {
+        index += 5;
+        skipTrivia();
+    }
+    const afterAsync = source.slice(index);
+    const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+    if (isFunction) {
+        index += 8;
+        skipTrivia();
+        if (source[index] === "*") {
+            index++;
+            skipTrivia();
+        }
+    }
+    else if (source[index] === "*") {
+        index++;
+        skipTrivia();
+    }
+    if (source[index] === "(") {
+        openIndex = index;
+        parenthesizedArrow = !isFunction;
+        asyncMethodOrArrow = isAsync && !isFunction;
+    }
+    else if (isFunction) {
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        skipTrivia();
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    else {
+        const identifierStart = index;
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        const firstIdentifier = source.slice(identifierStart, index);
+        skipTrivia();
+        if (source[index] === "=" && source[index + 1] === ">")
+            return undefined;
+        if (source[index] !== "(") {
+            if (firstIdentifier !== "get" && firstIdentifier !== "set")
+                return undefined;
+            if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+                return undefined;
+            index++;
+            while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+                index++;
+            skipTrivia();
+        }
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    if (openIndex < 0)
+        return undefined;
+    let depth = 1;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (index = openIndex + 1; index < source.length; index++) {
+        const character = source[index];
+        const nextCharacter = source[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote)
+                quote = undefined;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && source.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && source.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            depth++;
+        else if (character === ")") {
+            depth--;
+            if (depth === 0 && square === 0 && curly === 0) {
+                const closeIndex = index;
+                if (parenthesizedArrow) {
+                    index++;
+                    skipTrivia();
+                    const hasArrow = source[index] === "=" && source[index + 1] === ">";
+                    if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{"))
+                        return undefined;
+                }
+                return source.slice(openIndex + 1, closeIndex);
+            }
+            if (depth < 0)
+                return undefined;
+        }
+        else if (character === "[")
+            square++;
+        else if (character === "]") {
+            square--;
+            if (square < 0)
+                return undefined;
+        }
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+            if (curly < 0)
+                return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start) {
+    let source;
+    try {
+        source = Function.prototype.toString.call(start);
+    }
+    catch {
+        return false;
+    }
+    if (!source ||
+        source.includes("[native code]") ||
+        /^\s*(?:async\s+)?function\s+bound\b/.test(source))
+        return false;
+    const parameters = authStartParameterList(source);
+    if (!parameters)
+        return false;
+    const parts = splitAuthStartParameters(parameters);
+    if (!parts || parts.length < 2)
+        return false;
+    // Require ordinary, readable source formatting. This intentionally fails
+    // open for minified output and for transpilers that rewrite defaults.
+    const commaIndex = parameters.indexOf(",");
+    if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? ""))
+        return false;
+    const first = parts[0].trim();
+    const second = parts[1].trim();
+    const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+    const firstName = first.match(identifier)?.[0];
+    const secondName = second.match(identifier)?.[0];
+    if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3)
+        return false;
+    return /\s=\s/.test(second);
+}
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation() {
+    return function operation(config) {
+        return config;
+    };
+}
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation() {
+    return function streamOperation(config) {
+        return config;
+    };
 }
 function assertObjectConfig(value) {
     if (!value || typeof value !== "object") {
@@ -72,18 +484,95 @@ function assertLiteralField(value, field, validValues, providerId) {
         });
     }
 }
-function validateProviderShape(config) {
+function validateProxiedOAuthParams(value, field, providerId) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ValidationError(`Provider "${providerId}" auth.proxied.${field} must be an object of string values.`);
+    }
+    for (const [key, paramValue] of Object.entries(value)) {
+        if (!key.trim() || typeof paramValue !== "string") {
+            throw new ValidationError(`Provider "${providerId}" auth.proxied.${field} must contain non-empty keys and string values.`);
+        }
+        if (field === "authorizeParams" &&
+            PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+            throw new ValidationError(`Provider "${providerId}" auth.proxied.authorizeParams cannot override reserved parameter "${key}".`);
+        }
+    }
+}
+function validateProxiedOAuthAuth(auth, providerId) {
+    const proxied = auth.proxied;
+    if (auth.mode !== "oauth2_proxied") {
+        if (proxied !== undefined) {
+            throw new ValidationError(`Provider "${providerId}" auth.proxied is only valid when auth.mode is "oauth2_proxied".`);
+        }
+        return;
+    }
+    if (!proxied || typeof proxied !== "object" || Array.isArray(proxied)) {
+        throw new ValidationError(`Provider "${providerId}" with auth.mode "oauth2_proxied" must declare auth.proxied.`);
+    }
+    const config = Object.fromEntries(Object.entries(proxied));
+    for (const key of Object.keys(config)) {
+        if (!PROXIED_OAUTH_ALLOWED_FIELDS.has(key)) {
+            throw new ValidationError(`Provider "${providerId}" has unknown auth.proxied field "${key}".`);
+        }
+    }
+    for (const field of PROXIED_OAUTH_REQUIRED_FIELDS) {
+        if (typeof config[field] !== "string" || !config[field].trim()) {
+            throw new ValidationError(`Provider "${providerId}" auth.proxied.${field} must be a non-empty string.`);
+        }
+    }
+    for (const field of ["authorizeUrl", "tokenUrl"]) {
+        try {
+            const endpoint = new URL(String(config[field]));
+            if (endpoint.protocol !== "https:" ||
+                endpoint.username ||
+                endpoint.password ||
+                endpoint.hash) {
+                throw new Error("invalid endpoint");
+            }
+        }
+        catch {
+            throw new ValidationError(`Provider "${providerId}" auth.proxied.${field} must be an absolute HTTPS URL without credentials or a fragment.`);
+        }
+    }
+    const customScheme = String(config.customScheme);
+    if (!CUSTOM_SCHEME_REGEX.test(customScheme) ||
+        customScheme.toLowerCase().startsWith("http://") ||
+        customScheme.toLowerCase().startsWith("https://")) {
+        throw new ValidationError(`Provider "${providerId}" auth.proxied.customScheme must be a non-HTTP custom-scheme URL prefix.`);
+    }
+    if (!PROXIED_OAUTH_PROFILE_REGEX.test(String(config.rewriteProfile))) {
+        throw new ValidationError(`Provider "${providerId}" auth.proxied.rewriteProfile must be a kebab-case profile name.`);
+    }
+    if (!PROXIED_OAUTH_ENV_KEY_REGEX.test(String(config.clientIdEnvKey))) {
+        throw new ValidationError(`Provider "${providerId}" auth.proxied.clientIdEnvKey must be an APIFuse-style uppercase environment key.`);
+    }
+    if (config.pkce !== undefined && config.pkce !== "S256" && config.pkce !== "none") {
+        throw new ValidationError(`Provider "${providerId}" auth.proxied.pkce must be "S256" or "none".`);
+    }
+    validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
+    validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
+}
+function validateProviderDeclarationShape(config) {
     assertObjectConfig(config);
     assertRequiredField(config, "id");
     assertRequiredField(config, "version", String(config.id));
     assertRequiredField(config, "runtime", String(config.id));
     assertRequiredField(config, "meta", String(config.id));
-    assertRequiredField(config, "operations", String(config.id));
     if (typeof config.runtime === "string")
         assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+    if (config.native !== undefined && config.runtime === "browser") {
+        throw new ValidationError(`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`, {
+            fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+        });
+    }
     const auth = config.auth;
     if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
         assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
+    if (auth && typeof auth === "object" && !Array.isArray(auth)) {
+        validateProxiedOAuthAuth(Object.fromEntries(Object.entries(auth)), String(config.id));
+    }
     if (auth && typeof auth === "object" && "exchange" in auth) {
         throw new ProviderError(`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`, {
             fix: "Use the single canonical auth interface: auth.flow. Gateway calls auth.flow.start/continue/poll/abort/refresh only and persists complete turn data.credential as-is, so put login/token/session exchange inside auth.flow.continue.",
@@ -101,6 +590,19 @@ function validateProviderShape(config) {
             fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
         });
     }
+    if (auth &&
+        typeof auth === "object" &&
+        "flow" in auth &&
+        auth.flow &&
+        typeof auth.flow === "object" &&
+        "start" in auth.flow &&
+        typeof auth.flow.start === "function" &&
+        auth.flow.start.length <= 1 &&
+        authStartHasHiddenInput(auth.flow.start)) {
+        throw new ProviderError(`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`, {
+            fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+        });
+    }
     const access = config.access;
     if (access !== undefined) {
         if (!access || typeof access !== "object" || Array.isArray(access)) {
@@ -127,6 +629,10 @@ function validateProviderShape(config) {
         }
     }
 }
+function validateProviderImplementationShape(config) {
+    const configRecord = config;
+    assertRequiredField(configRecord, "operations", String(config.id));
+}
 function validateProviderProxy(config) {
     const proxy = config.proxy;
     if (proxy === undefined || typeof proxy === "boolean") {
@@ -137,11 +643,21 @@ function validateProviderProxy(config) {
             fix: `Use proxy: { mode: "required", provider: "smartproxy", geo: { country: "KR" }, session: { affinity: "connection", lifetimeMinutes: 30 } }`,
         });
     }
-    rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+    rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
     assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
     if (proxy.provider !== undefined) {
         assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
     }
+    if (proxy.providers !== undefined) {
+        if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+            throw new ValidationError(`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`, {
+                fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+            });
+        }
+        for (const vendor of proxy.providers) {
+            assertLiteralField(vendor, "proxy.providers[]", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+        }
+    }
     if (proxy.geo !== undefined) {
         if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.geo: must be an object.`, {
@@ -165,7 +681,7 @@ function validateProviderProxy(config) {
                 fix: `Use proxy.session: { affinity: "connection", lifetimeMinutes: 30 }.`,
             });
         }
-        rejectUnknownFields(proxy.session, new Set(["affinity", "lifetimeMinutes", "poolSize"]), "proxy.session");
+        rejectUnknownFields(proxy.session, new Set(["affinity", "lifetimeMinutes", "poolSize", "drainLeadSeconds"]), "proxy.session");
         if (proxy.session.affinity !== undefined) {
             assertLiteralField(proxy.session.affinity, "proxy.session.affinity", VALID_PROVIDER_PROXY_AFFINITIES, config.id);
         }
@@ -177,14 +693,70 @@ function validateProviderProxy(config) {
         if (poolSize !== undefined && (!Number.isInteger(poolSize) || poolSize <= 0)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`);
         }
-    }
-    if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-        const hasSmartproxySecret = config.secrets?.some((secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false);
-        if (!hasSmartproxySecret) {
-            throw new ValidationError(`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`, {
-                fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
+        const drainLeadSeconds = proxy.session.drainLeadSeconds;
+        if (drainLeadSeconds !== undefined &&
+            (!Number.isFinite(drainLeadSeconds) || drainLeadSeconds <= 0)) {
+            throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.drainLeadSeconds: must be a positive number of seconds.`, {
+                fix: `Use proxy.session.drainLeadSeconds: 120 to receive the sticky-expiry drain event 120s before hard expiry.`,
             });
         }
+        // A drain lead longer than the sticky lifetime would fire the expiring
+        // event before the session is even established, so the provider would
+        // never get a usable window. Reject the contradiction at build time.
+        if (drainLeadSeconds !== undefined &&
+            lifetime !== undefined &&
+            Number.isFinite(lifetime) &&
+            drainLeadSeconds >= lifetime * 60) {
+            throw new ValidationError(`Provider "${config.id}" has proxy.session.drainLeadSeconds (${drainLeadSeconds}s) greater than or equal to proxy.session.lifetimeMinutes (${lifetime}m).`, {
+                fix: `Lower drainLeadSeconds below the sticky lifetime so the drain event leaves a usable session window.`,
+            });
+        }
+    }
+    // Every credentialed vendor in a required-mode chain must declare its
+    // provider secret(s) so a missing credential fails at build/validation time,
+    // not during a live outage. This covers the fallback legs too (not just the
+    // first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+    // the chain silently down to a single vendor, reintroducing the SPOF the chain
+    // removes.
+    const vendorChain = proxy.providers && proxy.providers.length > 0
+        ? proxy.providers
+        : proxy.provider
+            ? [proxy.provider]
+            : [];
+    if (proxy.mode === "required") {
+        for (const vendor of vendorChain) {
+            const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+            if (!requiredSecrets)
+                continue;
+            for (const secretName of requiredSecrets) {
+                // Match the canonical runtime gate (assertRequiredSecretsPresent /
+                // listMissingRequiredSecrets), which enforces only `required === true`
+                // declarations. A declaration that omits `required` (defaulting to
+                // optional) is skipped at runtime, so accepting it here would pass
+                // validation while leaving the credential unenforced until proxy
+                // resolution during a live request — the fail-open gap this check exists
+                // to close.
+                const declared = config.secrets?.some((secret) => secret.name === secretName && secret.required === true);
+                if (!declared) {
+                    throw new ValidationError(`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`, {
+                        fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+                    });
+                }
+            }
+        }
+    }
+    // `decodo`/`custom` are deprecated vendor values (string-union members, so the
+    // @deprecated symbol gate can't catch them — warn at validation time instead).
+    const deprecatedVendors = vendorChain.filter((vendor) => vendor === "decodo" || vendor === "custom");
+    if (proxy.mode === "required" &&
+        vendorChain.length > 0 &&
+        deprecatedVendors.length === vendorChain.length) {
+        throw new ValidationError(`Provider "${config.id}" requires proxy egress but declares only deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}.`, {
+            fix: `Use proxy.provider or proxy.providers with "smartproxy" and/or "nodemaven".`,
+        });
+    }
+    if (deprecatedVendors.length > 0) {
+        console.warn(`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven".`);
     }
 }
 function validateProviderStt(config) {
@@ -199,6 +771,54 @@ function validateProviderStt(config) {
     rejectUnknownFields(stt, new Set(["mode"]), "stt");
     assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
 }
+function validateProviderOcr(config) {
+    const ocr = config.ocr;
+    if (ocr === undefined)
+        return;
+    if (!ocr || typeof ocr !== "object" || Array.isArray(ocr)) {
+        throw new ValidationError(`Provider "${config.id}" has invalid ocr: must be an object.`, {
+            fix: `Use ocr: { mode: "required" } or ocr: { mode: "optional" }.`,
+        });
+    }
+    rejectUnknownFields(ocr, new Set(["mode"]), "ocr");
+    assertLiteralField(ocr.mode, "ocr.mode", VALID_PROVIDER_OCR_MODES, config.id);
+}
+function validateProviderResolver(config) {
+    const resolver = config.resolver;
+    if (resolver === undefined)
+        return;
+    if (!resolver || typeof resolver !== "object" || Array.isArray(resolver)) {
+        throw new ValidationError(`Provider "${config.id}" has invalid resolver: must be an object.`, {
+            fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
+        });
+    }
+    rejectUnknownFields(resolver, new Set(["vendors", "kinds", "clientProfile"]), "resolver", config.id);
+    if (resolver.vendors !== undefined) {
+        validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
+    }
+    validateResolverLiteralArray(resolver.kinds, "resolver.kinds", VALID_PROVIDER_CHALLENGE_KINDS, config.id);
+    if (resolver.clientProfile !== undefined &&
+        (typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())) {
+        throw new ValidationError(`Provider "${config.id}" has invalid resolver.clientProfile: must be a non-empty string.`, {
+            fix: `Set resolver.clientProfile for provider "${config.id}" to a transport-owned profile name.`,
+        });
+    }
+}
+function validateResolverLiteralArray(value, field, validValues, providerId) {
+    if (!Array.isArray(value)) {
+        throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an array.`, {
+            fix: `Set ${field} for provider "${providerId}" to an array containing only: ${validValues.join(", ")}.`,
+        });
+    }
+    for (const [index, item] of value.entries()) {
+        if (typeof item === "string" && validValues.some((validValue) => validValue === item)) {
+            continue;
+        }
+        throw new ValidationError(`Provider "${providerId}" has invalid ${field}[${index}]: ${JSON.stringify(item)}. Expected one of: ${validValues.join(", ")}`, {
+            fix: `Set ${field}[${index}] for provider "${providerId}" to one of ${validValues.map((validValue) => `"${validValue}"`).join(", ")}.`,
+        });
+    }
+}
 function validateOperationIds(providerId, operations) {
     for (const operationName of Object.keys(operations)) {
         if (!OPERATION_ID_REGEX.test(operationName))
@@ -335,6 +955,23 @@ function validateOperationObservability(providerId, operations) {
         }
     }
 }
+function validateOperationErrorCodes(providerId, operations) {
+    for (const [operationName, operation] of Object.entries(operations)) {
+        for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+            if (errorCode.status !== undefined &&
+                !VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)) {
+                const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`, {
+                    fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+                });
+            }
+            if (errorCode.status !== undefined &&
+                SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)) {
+                console.warn(`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`);
+            }
+        }
+    }
+}
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
     "kind",
@@ -500,6 +1137,7 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
     "input",
     "prepareInput",
     "assertions",
+    "scenario",
     "degradedThresholdMs",
     "timeoutMs",
     "expectedStatus",
@@ -556,14 +1194,18 @@ function suggestField(unknown, candidates) {
     }
     return best;
 }
-function rejectUnknownFields(value, allowed, fieldPath) {
+function rejectUnknownFields(value, allowed, fieldPath, providerId) {
     for (const key of Object.keys(value)) {
         if (allowed.has(key))
             continue;
         const hint = suggestField(key, allowed);
         throw new ValidationError(hint
             ? `Unknown field "${key}" on ${fieldPath}. Did you mean "${hint}"?`
-            : `Unknown field "${key}" on ${fieldPath}.`, { fix: `Remove ${fieldPath}.${key} or rename it.` });
+            : `Unknown field "${key}" on ${fieldPath}.`, {
+            fix: providerId
+                ? `Remove ${fieldPath}.${key} from provider "${providerId}" or rename it.`
+                : `Remove ${fieldPath}.${key} or rename it.`,
+        });
     }
 }
 function assertBoundedIntegerMs(value, fieldPath, options) {
@@ -670,12 +1312,31 @@ function validateHealthCheckCase(providerId, operationName, caseValue, caseIndex
     const c = caseValue;
     if (typeof c.name !== "string" || c.name.length === 0)
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.name must be a non-empty string.`);
-    if (typeof c.assertions !== "function")
+    const hasScenario = c.scenario !== undefined;
+    const imperativeFields = [
+        ...(c.prepareInput === undefined ? [] : ["prepareInput"]),
+        ...(c.assertions === undefined ? [] : ["assertions"]),
+    ];
+    if (hasScenario && imperativeFields.length > 0)
+        throw new ValidationError(`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" cannot declare scenario with ${imperativeFields.join(" and ")}.`, {
+            fix: `Remove ${imperativeFields.map((field) => `${fieldPath}.${field}`).join(" and ")} and keep ${fieldPath}.scenario, or remove ${fieldPath}.scenario to keep the imperative hooks.`,
+        });
+    if (!hasScenario && typeof c.assertions !== "function")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.assertions must be a function.`, {
             fix: `Set ${fieldPath}.assertions to (ctx) => { ... } that throws on failure.`,
         });
     if (c.prepareInput !== undefined && typeof c.prepareInput !== "function")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.prepareInput must be a function.`);
+    if (hasScenario) {
+        const parsedScenario = HealthScenarioSchema.safeParse(c.scenario);
+        if (!parsedScenario.success)
+            throw new ValidationError(`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" has an invalid scenario: it must conform to HealthScenario.`, { fix: `Build ${fieldPath}.scenario with defineHealthScenario().` });
+        const unrelatedOperation = parsedScenario.data.coversOperations.find((operationId) => operationId !== operationName);
+        if (unrelatedOperation !== undefined)
+            throw new ValidationError(`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" scenario.coversOperations cannot claim unrelated operation "${unrelatedOperation}".`, {
+                fix: `Set ${fieldPath}.scenario.coversOperations to ["${operationName}"].`,
+            });
+    }
     if (c.degradedThresholdMs !== undefined &&
         (typeof c.degradedThresholdMs !== "number" ||
             !Number.isInteger(c.degradedThresholdMs) ||
@@ -776,6 +1437,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
     "manualTrigger",
     "steps",
     "run",
+    "scenario",
 ]);
 const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
@@ -1198,6 +1860,10 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
         }
         if (journey.manualTrigger !== undefined)
             validateHealthJourneyManualTrigger(providerId, journey.id, journey.manualTrigger);
+        if (journey.scenario !== undefined && journey.smsMatchers !== undefined)
+            throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers is not allowed on declarative scenarios.`);
+        if (journey.scenario !== undefined && journey.requiredSecrets !== undefined)
+            throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.requiredSecrets is not allowed on declarative scenarios.`);
         if (journey.timeout !== undefined)
             assertIsoDuration(journey.timeout, `Provider "${providerId}" healthJourneys.${journey.id}.timeout`);
         if (journey.cooldown !== undefined)
@@ -1239,6 +1905,21 @@ function validateOperationFixtures(providerId, operations) {
             throw new ValidationError(`Operation handler must be defined for provider "${providerId}" operation "${operationName}"`, {
                 fix: `Add operations.${operationName}.handler as an async function with signature (ctx, input) => Promise<output>`,
             });
+        if (operation.fixtures?.recordedAt !== undefined) {
+            const recordedAt = operation.fixtures.recordedAt;
+            const parsed = typeof recordedAt === "string"
+                ? new Date(`${recordedAt}T00:00:00.000Z`)
+                : new Date(Number.NaN);
+            const isCalendarDate = typeof recordedAt === "string" &&
+                /^\d{4}-\d{2}-\d{2}$/.test(recordedAt) &&
+                !Number.isNaN(parsed.getTime()) &&
+                parsed.toISOString().slice(0, 10) === recordedAt;
+            const kstToday = new Date(Date.now() + 9 * 60 * 60 * 1000).toISOString().slice(0, 10);
+            if (!isCalendarDate || recordedAt > kstToday)
+                throw new ValidationError(`Fixture recordedAt must be a valid, non-future KST calendar date for provider "${providerId}" operation "${operationName}"`, {
+                    fix: `Set operations.${operationName}.fixtures.recordedAt to the KST capture date in YYYY-MM-DD format; it must not be in the future.`,
+                });
+        }
         if (operation.fixtures?.request !== undefined) {
             const result = safeParseSchemaSync(operation.input, operation.fixtures.request, `operations.${operationName}.fixtures.request`);
             if (!result.success)
@@ -1257,6 +1938,28 @@ function validateOperationFixtures(providerId, operations) {
         }
     }
 }
+function resolveOperationFixtureRequests(operations) {
+    let changed = false;
+    const resolvedOperations = Object.fromEntries(Object.entries(operations).map(([operationName, operation]) => {
+        if (operation.fixtures?.request === undefined)
+            return [operationName, operation];
+        const request = resolveHealthCheckInputDateTokens(operation.fixtures.request);
+        if (request === operation.fixtures.request)
+            return [operationName, operation];
+        changed = true;
+        return [
+            operationName,
+            {
+                ...operation,
+                fixtures: {
+                    ...operation.fixtures,
+                    request,
+                },
+            },
+        ];
+    }));
+    return changed ? resolvedOperations : operations;
+}
 /**
  * Shallow shape guard only: the `deployment` object is passed through
  * verbatim and deliberately not deep-validated by the SDK — the APIFuse
@@ -1270,40 +1973,65 @@ function validateProviderDeployment(providerId, deployment) {
             fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
         });
 }
-export function defineProvider(config) {
-    validateProviderShape(config);
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider(declaration) {
+    validateProviderDeclaration(declaration);
+    const buildProvider = (implementation) => finalizeProvider({
+        ...declaration,
+        ...implementation,
+    });
+    return buildProvider;
+}
+function validateProviderDeclaration(config) {
+    validateProviderDeclarationShape(config);
     if (!CONNECTOR_ID_REGEX.test(config.id))
         throw new ProviderError(`Invalid provider id: "${config.id}"`, {
             fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
         });
-    if (Object.keys(config.operations).length === 0)
-        throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
-            fix: "Add at least one operation to the operations object",
-        });
-    validateOperationIds(config.id, config.operations);
-    validateOperationAnnotations(config.id, config.operations);
-    validateOperationObservability(config.id, config.operations);
-    validateOperationTransports(config.id, config.operations);
-    validateOperationContracts(config.id, config.operations);
-    validateToolRouterMetadata(config.id, config.operations);
-    const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
-    validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
     if (config.healthMonitor !== undefined && config.healthProbe !== undefined)
         throw new ValidationError(`Provider "${config.id}" declares both healthMonitor and healthProbe. They are aliases; declare exactly one.`, {
             fix: "Keep healthProbe (the new name) and delete the healthMonitor block.",
         });
     validateProviderHealthMonitor(config.id, config.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
-    validateOperationFixtures(config.id, config.operations);
     validateProviderDeployment(config.id, config.deployment);
+    try {
+        validateNativeProviderConfig(config.native);
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw new ValidationError(error.message);
+        throw error;
+    }
     validateProviderProxy(config);
+    validateProviderOcr(config);
     validateProviderStt(config);
+    validateProviderResolver(config);
     if (config.runtime === "browser" && !config.browser)
         throw new ProviderError(`Provider "${config.id}" must define browser.engine when runtime is "browser"`, {
             fix: 'Add browser: { engine: "playwright-stealth" } for TypeScript providers, or another supported engine for your runtime',
         });
     if (config.browser && config.runtime !== "browser")
         throw new ProviderError(`Provider "${config.id}" cannot define browser config unless runtime is "browser"`, { fix: 'Set runtime: "browser" or remove the browser config' });
-    return {
+    validateFailClosedProviderDeclaration(config);
+}
+function finalizeProvider(config) {
+    validateProviderImplementationShape(config);
+    const operations = resolveOperationFixtureRequests(config.operations);
+    if (Object.keys(config.operations).length === 0)
+        throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
+            fix: "Add at least one operation to the operations object",
+        });
+    validateOperationIds(config.id, config.operations);
+    validateOperationAnnotations(config.id, config.operations);
+    validateOperationObservability(config.id, config.operations);
+    validateOperationErrorCodes(config.id, config.operations);
+    validateOperationTransports(config.id, config.operations);
+    validateOperationContracts(config.id, config.operations);
+    validateToolRouterMetadata(config.id, config.operations);
+    const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
+    validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
+    validateOperationFixtures(config.id, operations);
+    const provider = {
         id: config.id,
         version: config.version,
         runtime: config.runtime,
@@ -1311,9 +2039,12 @@ export function defineProvider(config) {
         // are owned by the APIFuse registry builder, not the SDK.
         deployment: config.deployment,
         allowedHosts: config.allowedHosts,
+        native: config.native,
         stealth: config.stealth,
         proxy: config.proxy,
+        ocr: config.ocr,
         stt: config.stt,
+        resolver: config.resolver,
         browser: config.browser,
         auth: config.auth,
         reviewed: config.reviewed,
@@ -1322,11 +2053,15 @@ export function defineProvider(config) {
         credential: config.credential,
         context: config.context,
         meta: config.meta,
-        operations: config.operations,
+        operations,
         // Transitional healthMonitor → healthProbe alias: mirror whichever field
         // was declared onto both so old and new consumers keep working.
         healthMonitor: config.healthMonitor ?? config.healthProbe,
         healthProbe: config.healthProbe ?? config.healthMonitor,
         healthJourneys: config.healthJourneys,
     };
+    // Declaration validation never invokes handlers, so their declaration-bound
+    // context parameter is irrelevant to the runtime ProviderDefinition shape.
+    validateFailClosedOperationDeclaration(provider);
+    return provider;
 }