@apifuse/provider-sdk 2.2.0-beta.15 → 2.2.0-beta.17

package/dist/runtime/proxy-nodemaven.d.ts

@@ -3,6 +3,11 @@ export declare const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAM
 export declare const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
 export declare const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
 export declare const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+export type NodemavenCredentials = {
+    readonly username: string;
+    readonly password: string;
+    readonly filter?: string;
+};
 /** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
 export type ProxyProtocol = "http" | "socks5";
 /**
@@ -23,6 +28,8 @@ export type NodemavenSessionWindow = {
 export declare function nodemavenSessionWindow(policy: ProviderProxyPolicy, now?: number): NodemavenSessionWindow;
 export type NodemavenSynthesisInput = {
     policy: ProviderProxyPolicy;
+    /** Explicit credentials; synthesis never reads process-global state. */
+    credentials: NodemavenCredentials;
     affinityKey: string | undefined;
     protocol: ProxyProtocol;
     poolIndex: number;

package/dist/runtime/proxy-nodemaven.js

@@ -30,8 +30,8 @@ function readNodemavenUsername() {
 function readNodemavenPassword() {
     return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
 }
-function resolveNodemavenFilter() {
-    const raw = process.env[NODEMAVEN_FILTER_ENV]?.trim().toLowerCase();
+function resolveNodemavenFilter(value) {
+    const raw = value?.trim().toLowerCase();
     if (!raw)
         return DEFAULT_NODEMAVEN_FILTER;
     if (!NODEMAVEN_FILTERS.has(raw)) {
@@ -97,12 +97,12 @@ function selectPort(protocol, sid, poolIndex) {
  * There is no allocation API — geo/session are encoded in the username.
  */
 export function synthesizeNodemavenProxy(input) {
-    const username = readNodemavenUsername();
-    const password = readNodemavenPassword();
+    const username = input.credentials.username.trim();
+    const password = input.credentials.password.trim();
     if (!username || !password) {
         throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
     }
-    const filter = resolveNodemavenFilter();
+    const filter = resolveNodemavenFilter(input.credentials.filter);
     const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
     const port = selectPort(input.protocol, sid, input.poolIndex);
     const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);

package/dist/server/serve.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
@@ -15,7 +16,7 @@ import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
-import { createNativeNetworkClient } from "../runtime/native-network.js";
+import { createEnvVendorCredentialResolver, createNativeNetworkClient, } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
@@ -29,6 +30,7 @@ import { STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER, STATEFUL_SIG
 import { StatefulRoutingDeadlineError } from "../stateful/stateful-provider-session-routing.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
+import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import { createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
@@ -223,6 +225,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                         egress: provider.native.network,
                         proxyPolicy: resolveNativeProxyPolicy(provider),
                         affinityKey: proxyClientOptions.affinityKey,
+                        credentials: createEnvVendorCredentialResolver(env),
                     }),
                 },
             }
@@ -310,6 +313,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                             egress: provider.native.network,
                             proxyPolicy: resolveNativeProxyPolicy(provider),
                             affinityKey: proxyClientOptions.affinityKey,
+                            credentials: createEnvVendorCredentialResolver(createEnvContext(provider.secrets?.map((secret) => secret.name))),
                         }),
                     },
                 }
@@ -353,8 +357,8 @@ function zodDetails(error) {
         message: issue.message,
     }));
 }
-function toErrorResponse(error, requestId) {
-    const observability = errorObservabilityDetails(error);
+function toErrorResponse(error, requestId, declaredErrorCode) {
+    const observability = errorObservabilityDetails(error, declaredErrorCode);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
@@ -414,7 +418,10 @@ function toErrorResponse(error, requestId) {
 // narrowing from a ProviderError-typed value would collapse the negative branch
 // to `never`. Narrowing from unknown avoids that while still recognizing errors
 // from a duplicate SDK module instance.
-function providerObservabilityDetails(error) {
+function providerObservabilityDetails(error, declaredErrorCode) {
+    const declaredRetryable = sdkOwnsErrorResolution(error)
+        ? undefined
+        : declaredErrorCode?.retryable;
     // Session-expiry surfaces the credential_expired category + the opt-in
     // retryable signal so Gateway/Credential Service can refresh and re-drive the
     // operation (see design.md §4.3 D3). Without this branch the auth error would
@@ -424,7 +431,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     // Missing-secret errors carry the canonical credential_unavailable category
@@ -436,7 +443,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_unavailable",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     if (!isTransportError(error)) {
@@ -467,17 +474,23 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
-function errorObservabilityDetails(error) {
-    const providerDetails = providerObservabilityDetails(error);
+function errorObservabilityDetails(error, declaredErrorCode) {
+    const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
+    const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
     if (providerDetails)
         return providerDetails;
     if (error instanceof z.ZodError || isValidationError(error)) {
+        const declaredStatus = effectiveDeclaration?.status;
         return {
             category: isProviderError(error) && error.options?.category
                 ? error.options.category
-                : "input_validation",
+                : isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+                    ? "provider_error"
+                    : "input_validation",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+            retryable: isProviderError(error)
+                ? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+                : false,
         };
     }
     if (error instanceof StatefulRoutingDeadlineError) {
@@ -491,7 +504,7 @@ function errorObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "provider_error",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
         };
     }
     return {
@@ -500,9 +513,9 @@ function errorObservabilityDetails(error) {
         retryable: false,
     };
 }
-function responseWithErrorObservability(response, error) {
+function responseWithErrorObservability(response, error, declaredErrorCode) {
     const headers = new Headers(response.headers);
-    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)));
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -534,7 +547,11 @@ function publicProviderErrorMessage(error) {
     }
     return error.message;
 }
-function toStatusCode(error) {
+function isEmittableErrorStatus(value) {
+    return (typeof value === "number" &&
+        VALID_OPERATION_ERROR_STATUSES.some((status) => status === value));
+}
+function toStatusCode(error, declaredErrorCode) {
     if (error instanceof z.ZodError) {
         return 400;
     }
@@ -542,6 +559,10 @@ function toStatusCode(error) {
         return 504;
     }
     if (isProviderError(error)) {
+        if (!sdkOwnsErrorResolution(error) &&
+            isEmittableErrorStatus(declaredErrorCode?.status)) {
+            return declaredErrorCode.status;
+        }
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -576,82 +597,32 @@ function toStatusCode(error) {
     }
     return 500;
 }
-// Codes emitted by SDK-owned paths must never be attributed to provider
-// authors by the unregistered-code signal, even when their intentional status
-// is 500. Provider-authored codes not in this registry retain the signal.
-const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
-    "AUTH_PROMPT_UNAVAILABLE",
-    "BROWSER_CDP_POOL_REQUIRED",
-    "BROWSER_RUNTIME_UNSUPPORTED",
-    "STEALTH_RUNTIME_UNSUPPORTED",
-    "SSE_EVENT_UNDECLARED",
-    "STREAM_EVENT_TOO_LARGE",
-    "STREAM_CHUNK_TOO_LARGE",
-    "SSE_RESULT_UNSUPPORTED",
-    "STREAM_RESULT_UNSUPPORTED",
-    "AUTH_FLOW_NOT_CONFIGURED",
-    "refresh_not_supported",
-    "RUNTIME_UNSUPPORTED",
-    "PROVIDER_STATE_UNSUPPORTED",
-    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
-    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
-    "CHOICE_STATE_UNAVAILABLE",
-    "CHOICE_CONTEXT_REQUIRED",
-    "unsupported_stealth_cookie_store_version",
-    "provider_secret_error",
-    "credential_key_error",
-    "credential_mode_error",
-    "flow_expired",
-    "turn_validation_error",
-    "context_access_error",
-    "UNSUPPORTED_STT_OPTION",
-    "INVALID_STT_AUDIO",
-    "STT_AUDIO_TOO_LARGE",
-    "STT_UPSTREAM_FAILED",
-    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
-    "NO_CODE_FOUND",
-    "AMBIGUOUS_CODE",
-    "retry_invalid_policy",
-    "retry_unsafe_method",
-    "stealth_cookie_store_serialize_failed",
-    "response_too_large",
-    "transport_stream_unavailable",
-    "transport_invalid_method",
-    "http_transport_override_unsupported",
-    "http_redirect_policy_invalid",
-    "http_redirect_stopped",
-    "http_redirect_max_hops",
-    "http_redirect_missing_location",
-    "http_redirect_loop",
-    "transport_invalid_url",
-    "retry_exhausted",
-    "auth_abort_unsafe_data",
-    "credentials_auth_missing_credential_keys",
-    "credentials_auth_missing_credential",
-    "credentials_auth_invalid_login_result",
-    "credentials_auth_unknown_challenge",
-    "credentials_auth_unknown_pending_challenge",
-    "STATEFUL_FORWARDING_NOT_CONFIGURED",
-    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
-    "STATEFUL_FORWARDING_NONCE_INVALID",
-    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
-    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
-    "STATEFUL_FORWARDING_REPLAY_DETECTED",
-    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
-    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
-    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
-    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
-    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
-    "STATEFUL_FORWARDING_REQUEST_FAILED",
-    "STATEFUL_FORWARDING_CONTEXT_MISSING",
-    "STATEFUL_FORWARDING_BAD_RESPONSE",
-    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
-    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
-    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
-    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
-    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
-    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
-]);
+function sdkOwnsErrorResolution(error) {
+    if (isSessionExpiredError(error))
+        return true;
+    if (isTransportError(error))
+        return true;
+    if (error instanceof z.ZodError)
+        return true;
+    if (error instanceof StatefulRoutingDeadlineError)
+        return true;
+    return (isProviderError(error) &&
+        typeof error.code === "string" &&
+        SDK_RUNTIME_OWNED_ERROR_CODES.has(error.code));
+}
+function buildOperationErrorCodeLookup(provider) {
+    return new Map(Object.entries(provider.operations).flatMap(([operationId, operation]) => {
+        const errorCodes = operation.docs?.errorCodes;
+        return errorCodes?.length
+            ? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))]]
+            : [];
+    }));
+}
+function declaredErrorCodeFor(error, operationId, lookup) {
+    if (!operationId || !isProviderError(error) || typeof error.code !== "string")
+        return undefined;
+    return lookup.get(operationId)?.get(error.code);
+}
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -659,7 +630,7 @@ function extractRequestId(raw) {
     const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
     return typeof value === "string" ? value : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
@@ -669,12 +640,13 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = errorObservabilityDetails(error);
+    const details = errorObservabilityDetails(error, declaredErrorCode);
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
         !isValidationError(error) &&
         typeof error.code === "string" &&
-        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+        declaredErrorCode === undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -1270,6 +1242,7 @@ export function createServerApp(provider, options = {}) {
     validateStatefulServerConfig(options);
     const app = new Hono();
     const logger = options.logger ?? defaultProviderServerLogger;
+    const operationErrorCodes = buildOperationErrorCodeLookup(provider);
     const statefulForwardingReplayCache = new StatefulForwardingReplayCache(options.statefulForwarding?.replayCacheMaxEntries ??
         DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES);
     const state = options.state ??
@@ -1303,6 +1276,7 @@ export function createServerApp(provider, options = {}) {
     app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
         let rawBodyText = "";
         let rawBody;
+        let operationId;
         const operation = "stateful-internal";
         const requestCost = startRequestCost();
         try {
@@ -1388,7 +1362,7 @@ export function createServerApp(provider, options = {}) {
                 });
             }
             const request = operationRequestFromForwardingEnvelope(envelope);
-            const operationId = envelope.operationId;
+            operationId = envelope.operationId;
             const ctx = createProviderContext(provider, request, operationId, options, state);
             if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
                 throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt);
@@ -1405,13 +1379,14 @@ export function createServerApp(provider, options = {}) {
             return c.json({ data: output });
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
                 c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
             }
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            logProviderError(logger, provider, "operation", operationId || operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1439,13 +1414,14 @@ export function createServerApp(provider, options = {}) {
             return c.json(response);
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/auth/start", async (c) => {

package/dist/types.d.ts

@@ -610,9 +610,11 @@ export interface HealthMonitorProbeOverride {
     /** Optional degraded threshold override for generated registry probes. */
     degradedThresholdMs?: number;
 }
+export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 429, 500, 502, 503, 504];
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;
-    status?: number;
+    status?: ProviderErrorStatus;
     description: string;
     retryable?: boolean;
 }
@@ -1087,6 +1089,10 @@ export interface NativeTcpEgressRule {
 /**
  * Bounded native TCP egress discovered through a declared bootstrap endpoint.
  * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ * Dynamic rules must declare at least one target host selector through
+ * targetHostSuffixes and/or targetIpv4Cidrs. IPv4-literal grant targets match
+ * only targetIpv4Cidrs, while DNS-name targets match only targetHostSuffixes.
+ * CIDRs are exact IPv4 networks in a.b.c.d/nn form.
  *
  * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
  * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
@@ -1099,7 +1105,8 @@ export interface NativeTcpDynamicEgressRule {
     readonly sourceHostSuffixes?: readonly string[];
     readonly sourcePorts?: readonly number[];
     readonly sourcePortRanges?: readonly NativeTcpPortRange[];
-    readonly targetHostSuffixes: readonly string[];
+    readonly targetHostSuffixes?: readonly string[];
+    readonly targetIpv4Cidrs?: readonly string[];
     readonly targetPorts?: readonly number[];
     readonly targetPortRanges?: readonly NativeTcpPortRange[];
     readonly tls: NativeTcpTlsMode;

package/dist/types.js

@@ -32,6 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/package.json

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