@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/native-network-errors.js

@@ -0,0 +1,69 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.js";
+export class NativeNetworkError extends TransportError {
+    constructor(message, code, cause) {
+        const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+        super(message, {
+            code,
+            status: 0,
+            ...(cause ? { cause } : {}),
+            ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
+        });
+        this.name = "NativeNetworkError";
+    }
+    get code() {
+        return super.code;
+    }
+}
+export function safeDiagnosticEgressHost(value) {
+    const canonical = canonicalizeEgressHost(value);
+    return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+export class NativeProxyExpiredError extends NativeNetworkError {
+    expiresAt;
+    constructor(expiresAt) {
+        super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+        this.expiresAt = expiresAt;
+        this.name = "NativeProxyExpiredError";
+    }
+}
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+    port;
+    tls;
+    host;
+    constructor(host, port, tls) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`, "native_egress_not_declared");
+        this.port = port;
+        this.tls = tls;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressNotDeclaredError";
+    }
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export class NativeEgressGrantExpiredError extends NativeNetworkError {
+    port;
+    tls;
+    expiresAt;
+    host;
+    constructor(host, port, tls, expiresAt) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`, "native_egress_grant_expired");
+        this.port = port;
+        this.tls = tls;
+        this.expiresAt = expiresAt;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressGrantExpiredError";
+    }
+}
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export class NativeIdleTimeoutError extends NativeNetworkError {
+    constructor() {
+        super("Native network socket timed out while reading.", "native_connection_idle_timeout");
+        this.name = "NativeIdleTimeoutError";
+    }
+}

package/dist/runtime/native-network.d.ts

@@ -0,0 +1,105 @@
+import { Socket } from "node:net";
+import { type TLSSocket } from "node:tls";
+import { type ProxyProtocol, type ProxyTelemetrySink } from "../config/loader.js";
+import { type DynamicEgressRuleSnapshot } from "../native-egress-policy.js";
+import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
+import type { NativeTelemetrySink } from "./native-telemetry.js";
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./native-network-errors.js";
+export type { NativeNetworkErrorCode } from "./native-network-errors.js";
+export type NativeGatewayProxy = NativeProxyEgressInfo & {
+    readonly url: string;
+};
+export type NativeGatewayProxySynthesisInput = {
+    readonly vendor: ProviderProxyProvider;
+    readonly policy: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    readonly now: number;
+    readonly protocol: ProxyProtocol;
+    readonly credentials: VendorCredentialResolver;
+    /** Existing proxy lease telemetry; adapters may report detailed allocation facts. */
+    readonly telemetry?: ProxyTelemetrySink;
+};
+export type VendorCredentialLookup = {
+    readonly kind: "present";
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "absent";
+    readonly missing: readonly string[];
+};
+export type VendorCredentialResolver = (vendor: ProviderProxyProvider) => VendorCredentialLookup;
+export type NativeGatewayProxySkipReason = {
+    readonly kind: "credentials_absent";
+    readonly missing: readonly string[];
+} | {
+    readonly kind: "protocol_unsupported";
+    readonly protocol: string;
+} | {
+    readonly kind: "allocation_failed";
+    readonly cause: Error;
+} | {
+    readonly kind: "credential_lookup_failed";
+    readonly cause: Error;
+};
+export type NativeGatewayProxySynthesisResult = NativeGatewayProxy | {
+    readonly kind: "skipped";
+    readonly reason: NativeGatewayProxySkipReason;
+} | undefined;
+/** A vendor adapter in the ordered native gateway resolution chain. */
+export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxySynthesisResult | Promise<NativeGatewayProxySynthesisResult>;
+export type NativeGatewayProxyResolutionInput = {
+    readonly policy: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    readonly now?: number;
+    readonly protocol?: ProxyProtocol;
+    readonly credentials?: VendorCredentialResolver;
+    readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
+    readonly telemetry?: ProxyTelemetrySink;
+    readonly nativeTelemetry?: NativeTelemetrySink;
+};
+export type NativeNetworkClientOptions = {
+    /** Existing proxy lease contributor, shared with HTTP and stealth. */
+    readonly telemetry?: ProxyTelemetrySink;
+    /** Request-scoped connection, byte and lifecycle observations. */
+    readonly nativeTelemetry?: NativeTelemetrySink;
+    readonly proxyPolicy?: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    /** Stable credential/account identity; hashed before vendor synthesis. */
+    readonly credentialIdentity?: string;
+    /** Vendor credential lookup; defaults to the process EnvContext. */
+    readonly credentials?: VendorCredentialResolver;
+    /** Explicit CONNECT/SOCKS5 override; vendors otherwise choose their default. */
+    readonly proxyProtocol?: ProxyProtocol;
+    /** Vendor adapters in priority order within each policy vendor slot. */
+    readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
+    /** Warning-level lifecycle diagnostic sink. */
+    readonly warn?: (message: string) => void;
+    /**
+     * Provider-declared native egress. Undefined preserves legacy unrestricted
+     * behavior; any provided declaration, including an empty object, is enforced.
+     */
+    readonly egress?: NonNullable<NativeProviderConfig["network"]>;
+    /** Additional deployment authorization layered on top of SDK enforcement. */
+    readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
+};
+/** Build a resolver over the SDK's existing injectable environment context. */
+export declare function createEnvVendorCredentialResolver(env?: EnvContext): VendorCredentialResolver;
+/** Domain-separated, process-independent affinity derived from credential identity. */
+export declare function deriveNativeCredentialAffinityKey(credentialIdentity: string): string;
+/** Resolve the first configured native gateway, including allocation vendors. */
+export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): Promise<NativeGatewayProxy | undefined>;
+export declare function createNativeNetworkConnection(socket: Socket | TLSSocket, proxy: NativeGatewayProxy | undefined, options: NativeNetworkClientOptions, idleTimeoutMs?: number): NativeNetworkConnection;
+type NativeConnectTls = "required" | "disabled";
+export declare const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
+/** Internal validator-independent source selector matcher. */
+export declare function matchesSourceHost(rule: DynamicEgressRuleSnapshot, host: string): boolean;
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export declare function snapshotNativeConnectInput(input: NativeNetworkConnectInput): NativeNetworkConnectInput;
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export declare function snapshotNativeGrantInput(input: NativeNetworkDynamicGrantOptions): NativeNetworkDynamicGrantOptions;
+/** Internal authorization seam shared by production and SDK transport test doubles. */
+export declare function createNativeEgressAuthorization(options: NativeNetworkClientOptions): {
+    assertConnect(input: NativeNetworkConnectInput, tls: NativeConnectTls): void;
+    grant(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+};
+/** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
+export declare function createNativeNetworkClient(options?: NativeNetworkClientOptions): NativeNetworkClient;