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

package/src/runtime/keyring.ts

@@ -1,4 +1,4 @@
-import { ConfigurationError, decodeMasterKey } from "./key-derivation";
+import { ConfigurationError, decodeMasterKey } from "./key-derivation.js";
 
 export interface KeyRingOptions {
 	env: NodeJS.ProcessEnv;
@@ -16,16 +16,12 @@ export interface KeyRing {
 	accept(version: number): KeyRingEntry;
 	activeWriter(): KeyRingEntry;
 	versions(): number[];
-	purgeVersion(
-		version: number,
-		isActiveInStore: (v: number) => Promise<boolean>,
-	): Promise<void>;
+	purgeVersion(version: number, isActiveInStore: (v: number) => Promise<boolean>): Promise<void>;
 }
 
 const DEFAULT_KEY_PREFIX = "APIFUSE__KEYRING__MASTER_KEY_V";
 const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE__KEYRING__MASTER_KEY_ACCEPT_LIST";
-const DEFAULT_WRITER_VERSION_VAR =
-	"APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";
+const DEFAULT_WRITER_VERSION_VAR = "APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";
 
 function parseAcceptList(raw: string | undefined): number[] {
 	if (!raw || raw.trim().length === 0) {
@@ -56,19 +52,14 @@ function parseAcceptList(raw: string | undefined): number[] {
 	return versions;
 }
 
-function parseWriterVersion(
-	raw: string | undefined,
-	acceptList: number[],
-): number {
+function parseWriterVersion(raw: string | undefined, acceptList: number[]): number {
 	if (!raw || raw.trim().length === 0) {
 		throw new ConfigurationError("writer-version env var is empty");
 	}
 	const trimmed = raw.trim();
 	const v = Number.parseInt(trimmed, 10);
 	if (!Number.isInteger(v) || v <= 0 || String(v) !== trimmed) {
-		throw new ConfigurationError(
-			`writer-version "${trimmed}" is not a positive integer`,
-		);
+		throw new ConfigurationError(`writer-version "${trimmed}" is not a positive integer`);
 	}
 	if (!acceptList.includes(v)) {
 		throw new ConfigurationError(
@@ -90,8 +81,7 @@ export function loadKeyRing(options: KeyRingOptions): KeyRing {
 	const env = options.env;
 	const prefix = options.envPrefix ?? DEFAULT_KEY_PREFIX;
 	const acceptListVar = options.acceptListVar ?? DEFAULT_ACCEPT_LIST_VAR;
-	const writerVersionVar =
-		options.writerVersionVar ?? DEFAULT_WRITER_VERSION_VAR;
+	const writerVersionVar = options.writerVersionVar ?? DEFAULT_WRITER_VERSION_VAR;
 
 	const acceptList = parseAcceptList(env[acceptListVar]);
 	const writerVersion = parseWriterVersion(env[writerVersionVar], acceptList);
@@ -100,9 +90,7 @@ export function loadKeyRing(options: KeyRingOptions): KeyRing {
 	for (const version of acceptList) {
 		const raw = env[`${prefix}${version}`];
 		if (raw === undefined) {
-			throw new ConfigurationError(
-				`${prefix}${version} is missing (listed in accept-list)`,
-			);
+			throw new ConfigurationError(`${prefix}${version} is missing (listed in accept-list)`);
 		}
 		const key = decodeMasterKey(raw);
 		entries.set(version, { version, key });

package/src/runtime/namespace.ts

@@ -1,6 +1,6 @@
 import { createHmac } from "node:crypto";
 
-import { deriveSubkey } from "./key-derivation";
+import { deriveSubkey } from "./key-derivation.js";
 
 const HMAC_HEX_LENGTH = 16;
 
@@ -22,12 +22,7 @@ export function deriveContextNamespace(
 		throw new Error("sessionId is empty");
 	}
 
-	const subkey = deriveSubkey(
-		masterSecret,
-		providerId,
-		"context-namespace",
-		keyVersion,
-	);
+	const subkey = deriveSubkey(masterSecret, providerId, "context-namespace", keyVersion);
 	const hmac = createHmac("sha256", subkey).update(providerId).digest("hex");
 	return `provider:${hmac.slice(0, HMAC_HEX_LENGTH)}:${sessionId}`;
 }

package/src/runtime/native-network-errors.ts

@@ -0,0 +1,99 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.js";
+
+export type NativeNetworkErrorCode =
+	| "native_connection_aborted"
+	| "native_connection_closed"
+	| "native_connection_failed"
+	| "native_connection_idle_timeout"
+	| "native_connection_timeout"
+	| "native_egress_authorization_failed"
+	| "native_egress_grant_expired"
+	| "native_egress_grant_invalid"
+	| "native_egress_grant_limit_exceeded"
+	| "native_egress_input_invalid"
+	| "native_egress_not_declared"
+	| "native_egress_policy_invalid"
+	| "native_dynamic_egress_unsupported"
+	| "native_proxy_expired"
+	| "native_proxy_invalid";
+
+export class NativeNetworkError extends TransportError {
+	constructor(message: string, code: NativeNetworkErrorCode, cause?: Error) {
+		const isEgressPolicyFailure =
+			code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+		super(message, {
+			code,
+			status: 0,
+			...(cause ? { cause } : {}),
+			...(isEgressPolicyFailure ? { category: "provider_error" as const, retryable: false } : {}),
+		});
+		this.name = "NativeNetworkError";
+	}
+
+	override get code(): NativeNetworkErrorCode {
+		return super.code as NativeNetworkErrorCode;
+	}
+}
+
+export function safeDiagnosticEgressHost(value: unknown): string {
+	const canonical = canonicalizeEgressHost(value);
+	return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+
+export class NativeProxyExpiredError extends NativeNetworkError {
+	constructor(readonly expiresAt: string) {
+		super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+		this.name = "NativeProxyExpiredError";
+	}
+}
+
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`,
+			"native_egress_not_declared",
+		);
+		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 {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+		readonly expiresAt: string,
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`,
+			"native_egress_grant_expired",
+		);
+		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";
+	}
+}