@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

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

@@ -0,0 +1,96 @@
+import { Socket } from "node:net";
+import { type TLSSocket } from "node:tls";
+import { type ProxyProtocol } 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";
+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;
+};
+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[];
+};
+export type NativeNetworkClientOptions = {
+    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;