@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/define.js

@@ -1,7 +1,10 @@
 import ms from "ms";
-import { ProviderError, ValidationError } from "./errors";
-import { safeParseSchemaSync } from "./schema";
-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";
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
+import { ProviderError, ValidationError } from "./errors.js";
+import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
+import { safeParseSchemaSync } from "./schema.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"];
@@ -10,18 +13,34 @@ const VALID_AUTH_MODES = [
     "platform-managed",
     "credentials",
     "oauth2",
+    "oauth2_proxied",
 ];
-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 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", "nodemaven", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
@@ -30,25 +49,25 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 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 (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) 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",
-];
-const VALID_OPERATION_APPROVAL_POLICIES = [
-    "never",
-    "risk-based",
-    "always",
-];
-const VALID_OPERATION_TRANSPORT_KINDS = [
-    "json",
-    "sse",
-    "http-stream",
-    "websocket",
-];
+const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
+const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"];
+const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"];
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const MS_DURATION_PATTERN = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)?$/;
@@ -99,6 +118,76 @@ function assertLiteralField(value, field, validValues, providerId) {
         });
     }
 }
+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 validateProviderShape(config) {
     assertObjectConfig(config);
     assertRequiredField(config, "id");
@@ -109,11 +198,11 @@ function validateProviderShape(config) {
     if (typeof config.runtime === "string")
         assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
     const auth = config.auth;
-    if (auth &&
-        typeof auth === "object" &&
-        "mode" in auth &&
-        typeof auth.mode === "string")
+    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.",
@@ -167,15 +256,23 @@ 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)) {
+        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.`, {
                 fix: `Use proxy.geo: { country: "KR" } with ISO alpha-2 country codes.`,
             });
@@ -192,43 +289,90 @@ function validateProviderProxy(config) {
         }
     }
     if (proxy.session !== undefined) {
-        if (!proxy.session ||
-            typeof proxy.session !== "object" ||
-            Array.isArray(proxy.session)) {
+        if (!proxy.session || typeof proxy.session !== "object" || Array.isArray(proxy.session)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session: must be an object.`, {
                 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);
         }
         const lifetime = proxy.session.lifetimeMinutes;
-        if (lifetime !== undefined &&
-            (!Number.isFinite(lifetime) || lifetime <= 0)) {
+        if (lifetime !== undefined && (!Number.isFinite(lifetime) || lifetime <= 0)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.lifetimeMinutes: must be a positive number of minutes.`);
         }
         const poolSize = proxy.session.poolSize;
-        if (poolSize !== undefined &&
-            (!Number.isInteger(poolSize) || poolSize <= 0)) {
+        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 (deprecatedVendors.length > 0) {
+        console.warn(`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`);
+    }
 }
 function validateProviderStt(config) {
     const stt = config.stt;
     if (stt === undefined)
         return;
     if (!stt || typeof stt !== "object" || Array.isArray(stt)) {
-        throw new ValidationError(`Provider "${config.id}" has invalid stt: must be an object.`, { fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.` });
+        throw new ValidationError(`Provider "${config.id}" has invalid stt: must be an object.`, {
+            fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.`,
+        });
     }
     rejectUnknownFields(stt, new Set(["mode"]), "stt");
     assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
@@ -247,12 +391,7 @@ function validateOperationIds(providerId, operations) {
 }
 const OPERATION_CONTRACT_VERSION_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 const OPERATION_SENSITIVE_PATH_REGEX = /^(?:[A-Za-z0-9_$-]+|\*)(?:\.(?:[A-Za-z0-9_$-]+|\*))*$/;
-const VALID_OPERATION_LIFECYCLES = [
-    "stable",
-    "beta",
-    "deprecated",
-    "removed",
-];
+const VALID_OPERATION_LIFECYCLES = ["stable", "beta", "deprecated", "removed"];
 function assertNonEmptyString(value, field, providerId, operationName) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${field}: must be a non-empty string.`, { fix: `Set ${field} to a non-empty customer-facing value.` });
@@ -268,8 +407,7 @@ function validateToolRouterMetadata(providerId, operations) {
                 fix: `Remove operations.${operationName}.toolRouter or provide MCP-safe metadata.`,
             });
         }
-        if (toolRouter.name !== undefined &&
-            !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
+        if (toolRouter.name !== undefined && !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.name: expected an MCP-safe name.`, {
                 fix: `Use letters, numbers, and underscores only, starting with a letter, for example "${providerId.replace(/[^A-Za-z0-9]+/g, "_")}__${operationName.replace(/[^A-Za-z0-9]+/g, "_")}".`,
             });
@@ -307,8 +445,7 @@ function validateOperationContracts(providerId, operations) {
         if (contract.lifecycle !== undefined) {
             assertLiteralField(contract.lifecycle, `operations.${operationName}.contract.lifecycle`, VALID_OPERATION_LIFECYCLES, providerId);
         }
-        if (contract.lifecycle === "deprecated" ||
-            contract.lifecycle === "removed") {
+        if (contract.lifecycle === "deprecated" || contract.lifecycle === "removed") {
             if (!contract.deprecation || typeof contract.deprecation !== "object") {
                 throw new ValidationError(`Provider "${providerId}" operation "${operationName}" is ${contract.lifecycle} but lacks operations.${operationName}.contract.deprecation metadata.`, {
                     fix: `Add announcedAt, removalAfter, and migrationGuide to operations.${operationName}.contract.deprecation.`,
@@ -333,8 +470,7 @@ function validateOperationAnnotations(providerId, operations) {
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an integer number of milliseconds.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] (milliseconds).`,
             });
-        if (timeoutMs < OPERATION_TIMEOUT_MS_MIN ||
-            timeoutMs > OPERATION_TIMEOUT_MS_MAX)
+        if (timeoutMs < OPERATION_TIMEOUT_MS_MIN || timeoutMs > OPERATION_TIMEOUT_MS_MAX)
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}: ${timeoutMs} is outside [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms (the upper bound stays below the gateway/ALB ceiling).`,
             });
@@ -377,6 +513,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",
@@ -478,9 +631,7 @@ function validateOperationTransports(providerId, operations) {
                 assertStreamMs(maxDurationMs, `${fieldPath}.maxDurationMs`, STREAM_MAX_DURATION_MS_MIN, STREAM_MAX_DURATION_MS_MAX, "max duration");
                 assertPositiveBytes(Reflect.get(transport, "maxEventBytes"), `${fieldPath}.maxEventBytes`);
                 const resumable = Reflect.get(transport, "resumable");
-                if (resumable !== undefined &&
-                    resumable !== false &&
-                    resumable !== "last-event-id") {
+                if (resumable !== undefined && resumable !== false && resumable !== "last-event-id") {
                     throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.resumable: expected false or "last-event-id".`, {
                         fix: `Use ${fieldPath}.resumable: "last-event-id" for SSE Last-Event-ID resume support, or false to disable resume.`,
                     });
@@ -515,8 +666,7 @@ function validateOperationTransports(providerId, operations) {
                         });
                     }
                     for (const subprotocol of subprotocols) {
-                        if (typeof subprotocol !== "string" ||
-                            !WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)) {
+                        if (typeof subprotocol !== "string" || !WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)) {
                             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.subprotocols: each subprotocol must be an RFC token string.`, {
                                 fix: `Use values such as "apifuse.v1" without spaces or separators that are invalid for Sec-WebSocket-Protocol.`,
                             });
@@ -624,9 +774,7 @@ function assertBoundedIntegerMs(value, fieldPath, options) {
 function validateProviderHealthMonitor(providerId, healthMonitor, field = "healthMonitor") {
     if (healthMonitor === undefined)
         return;
-    if (!healthMonitor ||
-        typeof healthMonitor !== "object" ||
-        Array.isArray(healthMonitor))
+    if (!healthMonitor || typeof healthMonitor !== "object" || Array.isArray(healthMonitor))
         throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an object.`, {
             fix: `Set ${field} to { requiredSecrets?: string[]; serviceAccount?: string }`,
         });
@@ -676,9 +824,7 @@ function validateProviderHealthMonitor(providerId, healthMonitor, field = "healt
     }
     const probeOverrides = healthMonitorRecord.probeOverrides;
     if (probeOverrides !== undefined) {
-        if (!probeOverrides ||
-            typeof probeOverrides !== "object" ||
-            Array.isArray(probeOverrides))
+        if (!probeOverrides || typeof probeOverrides !== "object" || Array.isArray(probeOverrides))
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}.probeOverrides: must be an object keyed by probe id.`);
         for (const [probeId, override] of Object.entries(probeOverrides)) {
             if (probeId.length === 0)
@@ -756,9 +902,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
             fix: `Set ${fieldPath}.interval to a positive ms-style duration string.`,
         });
     if (s.schedule !== undefined) {
-        if (!s.schedule ||
-            typeof s.schedule !== "object" ||
-            Array.isArray(s.schedule)) {
+        if (!s.schedule || typeof s.schedule !== "object" || Array.isArray(s.schedule)) {
             throw new ValidationError(`Provider "${providerId}" ${fieldPath}.schedule must be an object.`);
         }
         if (Reflect.get(s.schedule, "jitter") !== undefined) {
@@ -784,8 +928,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
             label: "degraded threshold",
         });
     }
-    if (s.requiresConnection !== undefined &&
-        typeof s.requiresConnection !== "boolean")
+    if (s.requiresConnection !== undefined && typeof s.requiresConnection !== "boolean")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.requiresConnection must be a boolean.`);
     if (!Array.isArray(s.cases) || s.cases.length === 0)
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.cases must be a non-empty array.`, {
@@ -804,9 +947,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
 }
 function validateHealthCheckUnsupported(providerId, operationName, unsupported) {
     const fieldPath = `operations.${operationName}.healthCheckUnsupported`;
-    if (!unsupported ||
-        typeof unsupported !== "object" ||
-        Array.isArray(unsupported))
+    if (!unsupported || typeof unsupported !== "object" || Array.isArray(unsupported))
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
     rejectUnknownFields(unsupported, HEALTH_CHECK_UNSUPPORTED_FIELDS, fieldPath);
     const u = unsupported;
@@ -831,12 +972,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
     "steps",
     "run",
 ]);
-const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set([
-    "kind",
-    "interval",
-    "jitter",
-    "randomize",
-]);
+const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
     "id",
     "description",
@@ -854,10 +990,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS = new Set([
     "minManualInterval",
     "publicRationale",
 ]);
-const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set([
-    "enabled",
-    "reason",
-]);
+const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set(["enabled", "reason"]);
 const HEALTH_JOURNEY_MANUAL_TRIGGER_ENABLED_FIELDS = new Set([
     "enabled",
     "requiresAcknowledgement",
@@ -872,9 +1005,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS = new Set([
 ]);
 function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger) {
     const fieldPath = `healthJourneys.${journeyId}.manualTrigger`;
-    if (!manualTrigger ||
-        typeof manualTrigger !== "object" ||
-        Array.isArray(manualTrigger)) {
+    if (!manualTrigger || typeof manualTrigger !== "object" || Array.isArray(manualTrigger)) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object when present.`);
     }
     rejectUnknownFields(manualTrigger, HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS, fieldPath);
@@ -897,8 +1028,7 @@ function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.requiresAcknowledgement must be a boolean.`);
     }
     const risk = Reflect.get(manualTrigger, "risk");
-    if (typeof risk !== "string" ||
-        !HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)) {
+    if (typeof risk !== "string" || !HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.risk must be one of read_only, writes_external_state, or sms_or_payment.`);
     }
     if (risk !== "read_only" && requiresAcknowledgement !== true) {
@@ -950,7 +1080,7 @@ function isoDurationMs(value) {
     const hours = Number(/(\d+)H/.exec(value)?.[1] ?? 0);
     const minutes = Number(/(\d+)M/.exec(value)?.[1] ?? 0);
     const seconds = Number(/(\d+(?:\.\d+)?)S/.exec(value)?.[1] ?? 0);
-    return (days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000);
+    return days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000;
 }
 function scheduleRandomizationMs(randomize, fieldPath) {
     const mode = Reflect.get(randomize, "mode");
@@ -974,9 +1104,7 @@ function validateScheduleRandomization(randomize, fieldPath, intervalMs) {
         throw new ValidationError(`${fieldPath} must be an object.`);
     }
     const mode = Reflect.get(randomize, "mode");
-    const allowedFields = mode === "centered"
-        ? new Set(["mode", "maxOffset"])
-        : new Set(["mode", "maxDelay"]);
+    const allowedFields = mode === "centered" ? new Set(["mode", "maxOffset"]) : new Set(["mode", "maxDelay"]);
     rejectUnknownFields(randomize, allowedFields, fieldPath);
     const offsetMs = scheduleRandomizationMs(randomize, fieldPath);
     if (offsetMs <= 0) {
@@ -1062,9 +1190,7 @@ function countCapturingGroups(pattern) {
         const next = source[i + 1];
         if (next === "?" && source[i + 2] !== "<")
             continue;
-        if (next === "?" &&
-            source[i + 2] === "<" &&
-            (source[i + 3] === "=" || source[i + 3] === "!"))
+        if (next === "?" && source[i + 2] === "<" && (source[i + 3] === "=" || source[i + 3] === "!"))
             continue;
         count += 1;
     }
@@ -1142,8 +1268,7 @@ function validateSmsOtpMatcher(matcher, fieldPath) {
         throw new ValidationError(`${fieldPath}.code.pattern must be a RegExp or pattern source string.`);
     }
     const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern);
-    if (countCapturingGroups(regex) !== 1 &&
-        Reflect.get(code, "capture") === undefined) {
+    if (countCapturingGroups(regex) !== 1 && Reflect.get(code, "capture") === undefined) {
         throw new ValidationError(`${fieldPath}.code.pattern must contain exactly one OTP capture or declare code.capture.`);
     }
     if (Reflect.get(code, "capture") !== undefined &&
@@ -1195,8 +1320,7 @@ function validateHealthJourneySchedule(providerId, journeyId, schedule) {
     const interval = Reflect.get(schedule, "interval");
     assertIsoDuration(interval, `Provider "${providerId}" ${fieldPath}.interval`);
     const randomize = Reflect.get(schedule, "randomize");
-    if (Reflect.get(schedule, "jitter") !== undefined &&
-        randomize !== undefined) {
+    if (Reflect.get(schedule, "jitter") !== undefined && randomize !== undefined) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} cannot define both jitter and randomize.`);
     }
     if (Reflect.get(schedule, "jitter") !== undefined)
@@ -1226,8 +1350,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
             throw new ValidationError(`Provider "${providerId}" has duplicate health journey id "${journey.id}".`);
         journeyIds.add(journey.id);
         validateHealthJourneySchedule(providerId, journey.id, journey.schedule);
-        if (!Array.isArray(journey.coversOperations) ||
-            journey.coversOperations.length === 0) {
+        if (!Array.isArray(journey.coversOperations) || journey.coversOperations.length === 0) {
             throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.coversOperations must be a non-empty array.`);
         }
         for (const operationId of journey.coversOperations) {
@@ -1265,8 +1388,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.id must be a kebab-case identifier.`);
             if (step.operationId !== undefined && !operations[step.operationId])
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.operationId references unknown operation "${step.operationId}".`);
-            if (step.usesSmsMatcher !== undefined &&
-                !matcherIds.has(step.usesSmsMatcher))
+            if (step.usesSmsMatcher !== undefined && !matcherIds.has(step.usesSmsMatcher))
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.usesSmsMatcher references unknown matcher "${step.usesSmsMatcher}".`);
         }
         if (journey.manualTrigger !== undefined)
@@ -1300,9 +1422,7 @@ function validateOperationHealthChecks(providerId, operations, journeyCoveredOpe
             validateHealthCheckSuite(providerId, operationName, operation.healthCheck);
         if (hasUnsupported)
             validateHealthCheckUnsupported(providerId, operationName, operation.healthCheckUnsupported);
-        if (!hasCheck &&
-            !hasUnsupported &&
-            !journeyCoveredOperations.has(operationName))
+        if (!hasCheck && !hasUnsupported && !journeyCoveredOperations.has(operationName))
             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" declares neither healthCheck nor healthCheckUnsupported.`, {
                 fix: `Add \`healthCheck: { interval, cases: [...] }\` or \`healthCheckUnsupported: { reason: "..." }\` to operations.${operationName}.`,
             });
@@ -1314,6 +1434,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)
@@ -1332,8 +1467,44 @@ 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
+ * registry builder owns deployment validation and profile resolution.
+ */
+function validateProviderDeployment(providerId, deployment) {
+    if (deployment === undefined)
+        return;
+    if (!deployment || typeof deployment !== "object" || Array.isArray(deployment))
+        throw new ProviderError(`Provider "${providerId}" deployment must be an object when present`, {
+            fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
+        });
+}
 export function defineProvider(config) {
     validateProviderShape(config);
+    const operations = resolveOperationFixtureRequests(config.operations);
     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"',
@@ -1345,6 +1516,7 @@ export function defineProvider(config) {
     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);
@@ -1355,7 +1527,16 @@ export function defineProvider(config) {
             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);
+    validateOperationFixtures(config.id, 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);
     validateProviderStt(config);
     if (config.runtime === "browser" && !config.browser)
@@ -1368,7 +1549,11 @@ export function defineProvider(config) {
         id: config.id,
         version: config.version,
         runtime: config.runtime,
+        // Verbatim passthrough: deployment validation and profile resolution
+        // 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,
         stt: config.stt,
@@ -1380,7 +1565,7 @@ 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,