@fluid-app/exigo-connection-sdk 0.1.13 → 0.1.15

package/README.md

@@ -52,9 +52,9 @@ export const resolveExigoCredentials = defineExigoCredentials(
         database: c.exigoDbName,
         username: c.exigoDbUsername,
         password: c.exigoDbPassword,
-        // Required, no default: Exigo's replicas are Azure SQL, whose
-        // certificate does not match the host you connect to, so this must
-        // be true. It skips server certificate verification.
+        // Required, no default. true skips server certificate verification,
+        // which Exigo's replicas need: they present a certificate that does
+        // not verify against the host (e.g. SQL Server's self-signed one).
         trustServerCertificate: true,
       },
     };
@@ -154,8 +154,7 @@ const exigo = createExigoRestClient(rest, {
   reach Exigo, 503 when it could not verify the token or is at capacity.
 - Clients built with the same proxy URL and token share one agent, so a
   client per request still reuses open tunnels.
-- REST only. The proxy does not carry the SQL replica's port, and `mssql`
-  cannot use a proxy.
+- SQL goes through the same proxy; see [SQL through the egress proxy](#through-fluids-egress-proxy).
 
 ## 3. SQL
 
@@ -211,6 +210,44 @@ export default { serverExternalPackages: ["mssql"] };
 export const runtime = "nodejs";
 ```
 
+### Through Fluid's egress proxy
+
+The same proxy as for REST, for the same reason: Exigo allowlists the replica
+by source IP. `mssql` ignores proxy settings, so the pool hands tedious a
+connector that opens a CONNECT tunnel to the replica's host and port; TDS,
+including its TLS handshake, then runs through the tunnel unchanged. No extra
+package is needed.
+
+```ts
+const pool = await getExigoPool(creds, {
+  egressProxy: process.env.FLUID_EGRESS_PROXY_URL
+    ? {
+        url: process.env.FLUID_EGRESS_PROXY_URL,
+        token: installation.authenticationToken, // dit_…
+      }
+    : undefined,
+});
+```
+
+- The proxy must allow the replica's host and port (1433), and Exigo must
+  allowlist the proxy's IP on the SQL side.
+- The proxy and token are part of the pool's identity: a call with a different
+  one gets its own pool.
+- Encryption is required through the proxy. `encrypt: false` is refused
+  (`ExigoCredentialsError`). And because SQL Server negotiates TLS (tedious
+  skips it, sending the login with the password merely obfuscated, when the
+  server's PRELOGIN answer does not offer encryption), the connector reads that
+  answer and hangs up before the login unless encryption is `ON` or `REQ`,
+  throwing `ExigoConnectionError`. Direct connections are not checked this way.
+- Refusals throw `ExigoProxyError` with `source: "sql"`; a proxy that cannot be
+  reached throws `ExigoConnectionError` naming it.
+- **Known gap:** the connection is encrypted, but with
+  `trustServerCertificate: true` nothing proves the other end of the TLS is
+  Exigo. The proxy reads nothing inside the tunnel, yet anything between the
+  proxy and Exigo that impersonates the replica could read the login. Direct
+  connections carry the same gap. Closing it needs a certificate on Exigo's
+  side that can be verified.
+
 ## Errors
 
 Every error extends `ExigoError`. None of them carries a password or an

package/dist/egress-proxy.d.mts

@@ -0,0 +1,24 @@
+//#region src/egress-proxy.d.ts
+/**
+* Fluid's egress proxy: a CONNECT-only forward proxy with a static outbound IP
+* that Exigo tenants allowlist, for apps on hosts whose egress IPs are not
+* Fluid's (Mist apps on Vercel). It tunnels bytes without reading them; what
+* keeps the Exigo credentials from it is the TLS inside the tunnel.
+*/
+interface ExigoEgressProxy {
+  /**
+  * The proxy URL, which Fluid provides to a droplet-linked Mist app as
+  * `FLUID_EGRESS_PROXY_URL`. Must be https: the CONNECT request carries the
+  * token outside the tunnel. Plain http is accepted only for a loopback host,
+  * such as a proxy run locally.
+  */
+  readonly url: string;
+  /**
+  * The droplet installation token (`dit_…`, the `authentication_token` of the
+  * install webhook) the proxy authenticates the app with. A `Bearer ` prefix
+  * is optional.
+  */
+  readonly token: string;
+}
+//#endregion
+export { ExigoEgressProxy };

package/dist/egress-proxy.mjs

@@ -0,0 +1,53 @@
+import { ExigoCredentialsError } from "./errors.mjs";
+//#region src/egress-proxy.ts
+/**
+* Fluid's egress proxy, as both clients use it: what an app passes, how it is
+* checked, and what a refusal means. No Node-only APIs, so `./rest` can import
+* it; the SQL tunnel itself lives in `./sql-tunnel`.
+*/
+const LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/** Same rule as the REST base URL: the CONNECT request carries the token in clear. */
+function normalizeUrl(proxyUrl) {
+	let url;
+	try {
+		url = new URL(proxyUrl.trim());
+	} catch {
+		throw new ExigoCredentialsError("Exigo egressProxy.url is not a valid URL.", ["egressProxy.url"]);
+	}
+	const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+	if (url.protocol !== "https:" && !loopbackHttp) throw new ExigoCredentialsError("Exigo egressProxy.url must be an https URL; the CONNECT request carries the token.", ["egressProxy.url"]);
+	if (url.username || url.password) throw new ExigoCredentialsError("Exigo egressProxy.url must not carry credentials; pass the token instead.", ["egressProxy.url"]);
+	return url;
+}
+function normalizeToken(token) {
+	const bare = token.replace(/^\s*Bearer(?:\s+|$)/i, "").trim();
+	if (bare === "" || /\s/.test(bare)) throw new ExigoCredentialsError("Exigo egressProxy.token must be the droplet installation token (dit_…).", ["egressProxy.token"]);
+	return bare;
+}
+/** Throws `ExigoCredentialsError` for a URL or token that cannot work. */
+function normalizeEgressProxy(proxy) {
+	const url = normalizeUrl(proxy.url);
+	return {
+		url: url.origin,
+		host: url.host,
+		token: normalizeToken(proxy.token)
+	};
+}
+/** What each answer to CONNECT means, and what to check. */
+function describeProxyRefusal(status, target, proxyHost) {
+	const prefix = `Fluid's egress proxy at ${proxyHost} refused the tunnel to ${target} (HTTP ${status})`;
+	switch (status) {
+		case 407: return `${prefix}: it did not accept the token. Pass the droplet installation token (dit_…) as egressProxy.token.`;
+		case 403: return `${prefix}: this droplet may not egress through it, or ${target} is not on its allowlist.`;
+		case 502: return `${prefix}: it could not reach Exigo.`;
+		case 503: return `${prefix}: it could not verify the token with Fluid or is at capacity. Retry.`;
+		case 504: return `${prefix}: its connection to Exigo timed out. Retry.`;
+		default: return `${prefix}.`;
+	}
+}
+//#endregion
+export { LOOPBACK_HOSTS, describeProxyRefusal, normalizeEgressProxy };

package/dist/rest.d.mts

@@ -1,5 +1,6 @@
 import { ExigoRestCredentials } from "./credentials.mjs";
 import { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoProxyError, ExigoSource, ExigoTimeoutError } from "./errors.mjs";
+import { ExigoEgressProxy } from "./egress-proxy.mjs";
 
 //#region src/rest.d.ts
 declare const EXIGO_API_VERSION = "3.0";
@@ -21,27 +22,6 @@ interface ExigoRequestOptions {
 }
 type ExigoMethodOptions = Omit<ExigoRequestOptions, "body">;
 type ExigoBodyMethodOptions = ExigoRequestOptions;
-/**
-* Fluid's egress proxy: a CONNECT-only forward proxy with a static outbound IP
-* that Exigo tenants allowlist, for apps on hosts whose egress IPs are not
-* Fluid's (Mist apps on Vercel). TLS stays end to end between the app and
-* Exigo; the proxy never sees the Exigo credentials.
-*/
-interface ExigoEgressProxy {
-  /**
-  * The proxy URL, which Fluid provides to a droplet-linked Mist app as
-  * `FLUID_EGRESS_PROXY_URL`. Must be https: the CONNECT request carries the
-  * token outside the tunnel. Plain http is accepted only for a loopback host,
-  * such as a proxy run locally.
-  */
-  readonly url: string;
-  /**
-  * The droplet installation token (`dit_…`, the `authentication_token` of the
-  * install webhook) the proxy authenticates the app with. A `Bearer ` prefix
-  * is optional.
-  */
-  readonly token: string;
-}
 interface ExigoRestClientOptions {
   /** Per-request timeout. Defaults to {@link DEFAULT_EXIGO_TIMEOUT_MS}. */
   readonly timeoutMs?: number;
@@ -94,4 +74,4 @@ declare function normalizeExigoBaseUrl(baseUrl: string): string;
 */
 declare function createExigoRestClient(credentials: ExigoRestCredentials | null | undefined, options?: ExigoRestClientOptions): ExigoRestClient;
 //#endregion
-export { DEFAULT_EXIGO_TIMEOUT_MS, EXIGO_API_VERSION, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoBodyMethodOptions, ExigoConnectionError, ExigoCredentialsError, ExigoEgressProxy, ExigoError, ExigoErrorOptions, ExigoHttpMethod, ExigoMethodOptions, ExigoProxyError, ExigoQueryValue, ExigoRequestOptions, ExigoRestClient, ExigoRestClientOptions, type ExigoRestCredentials, ExigoSource, ExigoTimeoutError, createExigoRestClient, normalizeExigoBaseUrl };
+export { DEFAULT_EXIGO_TIMEOUT_MS, EXIGO_API_VERSION, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoBodyMethodOptions, ExigoConnectionError, ExigoCredentialsError, type ExigoEgressProxy, ExigoError, ExigoErrorOptions, ExigoHttpMethod, ExigoMethodOptions, ExigoProxyError, ExigoQueryValue, ExigoRequestOptions, ExigoRestClient, ExigoRestClientOptions, type ExigoRestCredentials, ExigoSource, ExigoTimeoutError, createExigoRestClient, normalizeExigoBaseUrl };

package/dist/rest.mjs

@@ -1,5 +1,6 @@
 import { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoProxyError, ExigoTimeoutError } from "./errors.mjs";
 import { assertExigoRestCredentials } from "./credentials.mjs";
+import { LOOPBACK_HOSTS, describeProxyRefusal, normalizeEgressProxy } from "./egress-proxy.mjs";
 //#region src/rest.ts
 /**
 * `@fluid-app/exigo-connection-sdk/rest`: one way to call Exigo's REST API.
@@ -18,11 +19,6 @@ const EXIGO_API_VERSION = "3.0";
 const DEFAULT_EXIGO_TIMEOUT_MS = 15e3;
 const BODY_SNIPPET_LENGTH = 500;
 const VERSION_SEGMENT = /^\d+\.\d+$/;
-const LOOPBACK_HOSTS = new Set([
-	"localhost",
-	"127.0.0.1",
-	"[::1]"
-]);
 /**
 * `https://acme-api.exigo.com`, `…/3.0` and `…/3.0/` all become
 * `https://acme-api.exigo.com/3.0`. A base URL ending in any other version
@@ -137,24 +133,6 @@ function validTimeout(timeoutMs) {
 	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMEOUT_MS) throw new TypeError(`Exigo timeoutMs must be a positive number up to ${MAX_TIMEOUT_MS}, got ${timeoutMs}.`);
 	return timeoutMs;
 }
-/** Same rule as the base URL: the CONNECT request carries the token in clear. */
-function normalizeEgressProxyUrl(proxyUrl) {
-	let url;
-	try {
-		url = new URL(proxyUrl.trim());
-	} catch {
-		throw new ExigoCredentialsError("Exigo egressProxy.url is not a valid URL.", ["egressProxy.url"]);
-	}
-	const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
-	if (url.protocol !== "https:" && !loopbackHttp) throw new ExigoCredentialsError("Exigo egressProxy.url must be an https URL; the CONNECT request carries the token.", ["egressProxy.url"]);
-	if (url.username || url.password) throw new ExigoCredentialsError("Exigo egressProxy.url must not carry credentials; pass the token instead.", ["egressProxy.url"]);
-	return url.origin;
-}
-function normalizeEgressProxyToken(token) {
-	const bare = token.replace(/^\s*Bearer(?:\s+|$)/i, "").trim();
-	if (bare === "" || /\s/.test(bare)) throw new ExigoCredentialsError("Exigo egressProxy.token must be the droplet installation token (dit_…).", ["egressProxy.token"]);
-	return bare;
-}
 /**
 * One proxy agent per proxy URL and token, shared by every client that uses
 * them, so a droplet building a client per request still reuses its tunnels.
@@ -195,17 +173,6 @@ function proxyRefusalStatus(error) {
 	}
 	return null;
 }
-function describeProxyRefusal(status, host, proxyHost) {
-	const prefix = `Fluid's egress proxy at ${proxyHost} refused the tunnel to ${host} (HTTP ${status})`;
-	switch (status) {
-		case 407: return `${prefix}: it did not accept the token. Pass the droplet installation token (dit_…) as egressProxy.token.`;
-		case 403: return `${prefix}: this droplet may not egress through it, or ${host} is not on its allowlist.`;
-		case 502: return `${prefix}: it could not reach Exigo.`;
-		case 503: return `${prefix}: it could not verify the token with Fluid or is at capacity. Retry.`;
-		case 504: return `${prefix}: its connection to Exigo timed out. Retry.`;
-		default: return `${prefix}.`;
-	}
-}
 /**
 * Creates a client for one set of REST credentials.
 *
@@ -219,11 +186,8 @@ function createExigoRestClient(credentials, options = {}) {
 	const baseUrl = normalizeExigoBaseUrl(credentials.baseUrl);
 	const host = new URL(baseUrl).host;
 	const authorization = authorizationHeader(credentials);
-	const egressProxy = options.egressProxy ? {
-		url: normalizeEgressProxyUrl(options.egressProxy.url),
-		token: normalizeEgressProxyToken(options.egressProxy.token)
-	} : null;
-	const proxyHost = egressProxy ? new URL(egressProxy.url).host : null;
+	const egressProxy = options.egressProxy ? normalizeEgressProxy(options.egressProxy) : null;
+	const proxyHost = egressProxy?.host ?? null;
 	const secrets = [
 		credentials.password,
 		authorization.replace(/^Basic /, ""),

package/dist/sql-tunnel.mjs

@@ -0,0 +1,172 @@
+import { ExigoConnectionError, ExigoProxyError } from "./errors.mjs";
+import { describeProxyRefusal } from "./egress-proxy.mjs";
+import * as net from "node:net";
+import * as tls from "node:tls";
+//#region src/sql-tunnel.ts
+/**
+* Opens SQL Server connections through Fluid's egress proxy.
+*
+* tedious, which `mssql` drives, ignores proxy settings but accepts a
+* `connector` that hands it an already-connected socket. This one opens a
+* CONNECT tunnel to the server's host and port and returns the socket once the
+* proxy answers 200; tedious then speaks TDS through it exactly as it would on
+* a direct connection, including the TLS handshake, which the proxy cannot
+* read. Redirects from the server (`routingData`) are tunnelled too, because
+* tedious calls the connector with whatever host and port it is dialling.
+*
+* With `encrypt: true` tedious only starts TLS when the server's PRELOGIN
+* answer offers it; a server, or anything impersonating one, that answers
+* NOT_SUP or OFF would get the login with its password merely obfuscated. The
+* connector sees the raw bytes first, so it reads that answer and hangs up
+* before tedious can send the login unless encryption is ON or REQ.
+*/
+/** A proxy's response head is a few hundred bytes; past this it is not one. */
+const MAX_RESPONSE_HEAD_BYTES = 16 * 1024;
+function authority(host, port) {
+	return net.isIPv6(host) ? `[${host}]:${port}` : `${host}:${port}`;
+}
+function dialProxy(proxyUrl) {
+	const port = Number(proxyUrl.port || (proxyUrl.protocol === "https:" ? 443 : 80));
+	const host = proxyUrl.hostname.replace(/^\[(.*)\]$/, "$1");
+	if (proxyUrl.protocol !== "https:") return net.connect({
+		host,
+		port
+	});
+	return tls.connect({
+		host,
+		port,
+		servername: net.isIP(host) ? void 0 : host
+	});
+}
+/**
+* Resolves with the proxy's status once the response head has arrived, and
+* any bytes after it, which belong to the tunnel.
+*/
+function readResponseHead(socket, ready, request, signal) {
+	return new Promise((resolve, reject) => {
+		let buffered = Buffer.alloc(0);
+		const cleanup = () => {
+			socket.off(ready, onReady);
+			socket.off("data", onData);
+			socket.off("error", onError);
+			socket.off("close", onClose);
+			signal.removeEventListener("abort", onAbort);
+		};
+		const fail = (error) => {
+			cleanup();
+			socket.destroy();
+			reject(error);
+		};
+		const onReady = () => {
+			socket.write(request);
+		};
+		const onData = (chunk) => {
+			buffered = Buffer.concat([buffered, chunk]);
+			const end = buffered.indexOf("\r\n\r\n");
+			if (end === -1) {
+				if (buffered.length > MAX_RESPONSE_HEAD_BYTES) fail(/* @__PURE__ */ new Error("the proxy's response head is too long"));
+				return;
+			}
+			const statusLine = buffered.subarray(0, buffered.indexOf("\r\n")).toString("latin1");
+			const match = /^HTTP\/1\.[01] (\d{3})\b/.exec(statusLine);
+			if (!match) {
+				fail(/* @__PURE__ */ new Error("the proxy did not answer with HTTP"));
+				return;
+			}
+			cleanup();
+			socket.pause();
+			resolve({
+				status: Number(match[1]),
+				rest: buffered.subarray(end + 4)
+			});
+		};
+		const onError = (error) => fail(error);
+		const onClose = () => fail(/* @__PURE__ */ new Error("the proxy closed the connection before answering"));
+		const onAbort = () => fail(signal.reason);
+		if (signal.aborted) {
+			fail(signal.reason);
+			return;
+		}
+		socket.once(ready, onReady);
+		socket.on("data", onData);
+		socket.on("error", onError);
+		socket.on("close", onClose);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** A tedious connector that dials every SQL connection through the proxy. */
+function egressProxyConnector(proxy) {
+	const proxyUrl = new URL(proxy.url);
+	return async ({ host, port }, _lookup, signal) => {
+		const target = authority(host, port);
+		const socket = dialProxy(proxyUrl);
+		const request = `CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\nProxy-Authorization: Bearer ${proxy.token}\r\n\r
+`;
+		let head;
+		try {
+			head = await readResponseHead(socket, proxyUrl.protocol === "https:" ? "secureConnect" : "connect", request, signal);
+		} catch (error) {
+			if (signal.aborted) throw error;
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new ExigoConnectionError(`Could not reach Fluid's egress proxy at ${proxy.host}: ${reason}`, "sql", { cause: error });
+		}
+		if (head.status !== 200) {
+			socket.destroy();
+			throw new ExigoProxyError(describeProxyRefusal(head.status, target, proxy.host), "sql", { status: head.status });
+		}
+		refuseUnencryptedPrelogin(socket, target);
+		if (head.rest.length > 0) socket.unshift(head.rest);
+		return socket;
+	};
+}
+const TDS_HEADER_LENGTH = 8;
+const TDS_TABULAR_RESULT = 4;
+const PRELOGIN_ENCRYPTION = 1;
+const PRELOGIN_TERMINATOR = 255;
+const ENCRYPTION_NAMES = {
+	0: "OFF",
+	1: "ON",
+	2: "NOT_SUP",
+	3: "REQ"
+};
+const ENCRYPTED = new Set([1, 3]);
+/** A PRELOGIN answer is tens of bytes; past this it is not one. */
+const MAX_PRELOGIN_BYTES = 4 * 1024;
+/** The ENCRYPTION option of a PRELOGIN answer, or null if there is none. */
+function preloginEncryption(packet) {
+	if (packet.length < TDS_HEADER_LENGTH || packet[0] !== TDS_TABULAR_RESULT) return null;
+	const payload = packet.subarray(TDS_HEADER_LENGTH);
+	for (let index = 0; index + 5 <= payload.length; index += 5) {
+		const type = payload[index];
+		if (type === PRELOGIN_TERMINATOR) return null;
+		if (type !== PRELOGIN_ENCRYPTION) continue;
+		const offset = payload.readUInt16BE(index + 1);
+		if (payload.readUInt16BE(index + 3) < 1 || offset >= payload.length) return null;
+		return payload[offset] ?? null;
+	}
+	return null;
+}
+function refuseUnencryptedPrelogin(socket, target) {
+	let buffered = Buffer.alloc(0);
+	const refuse = (detail) => {
+		socket.destroy(new ExigoConnectionError(`Exigo's SQL Server at ${target} did not agree to encrypt the connection (${detail}); the login was not sent.`, "sql"));
+	};
+	const onData = (chunk) => {
+		buffered = Buffer.concat([buffered, chunk]);
+		if (buffered.length < TDS_HEADER_LENGTH) return;
+		const length = buffered.readUInt16BE(2);
+		if (length < TDS_HEADER_LENGTH || length > MAX_PRELOGIN_BYTES) {
+			socket.off("data", onData);
+			refuse("its first answer is not a PRELOGIN response");
+			return;
+		}
+		if (buffered.length < length) return;
+		socket.off("data", onData);
+		const encryption = preloginEncryption(buffered.subarray(0, length));
+		if (encryption === null) refuse("its PRELOGIN response carries no encryption option");
+		else if (!ENCRYPTED.has(encryption)) refuse(`PRELOGIN encryption ${ENCRYPTION_NAMES[encryption] ?? encryption}`);
+	};
+	socket.on("data", onData);
+}
+//#endregion
+export { egressProxyConnector };

package/dist/sql.d.mts

@@ -1,5 +1,6 @@
 import { ExigoSqlCredentials } from "./credentials.mjs";
 import { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoProxyError, ExigoSource, ExigoTimeoutError } from "./errors.mjs";
+import { ExigoEgressProxy } from "./egress-proxy.mjs";
 import { ConnectionPool, ConnectionPool as ConnectionPool$1 } from "mssql";
 
 //#region src/sql.d.ts
@@ -24,6 +25,14 @@ interface ExigoPoolOptions {
   * dropped. Defaults to a `console.warn`; the pool replaces the connection.
   */
   readonly onError?: (error: ExigoError | Error) => void;
+  /**
+  * Dials every connection through Fluid's egress proxy, for an app whose
+  * outbound IP Exigo does not allowlist. Leave it unset to connect directly,
+  * as in local development. Part of the pool's identity: a call with a
+  * different proxy or token gets its own pool. Requires `encrypt`, so the
+  * login never crosses the proxy in clear.
+  */
+  readonly egressProxy?: ExigoEgressProxy;
 }
 /**
 * Turns an `mssql` failure into the package's typed errors where Exigo's
@@ -35,8 +44,8 @@ declare function translateExigoSqlError(error: unknown): unknown;
 * The open pool for these credentials, opening it on first use.
 *
 * Pools are keyed by host, port, database and username, and within that by
-* password and TLS settings. Concurrent first calls share one connect. A
-* failed connect is not cached, so the next call tries again. A rotated
+* password, TLS settings and egress proxy. Concurrent first calls share one
+* connect. A failed connect is not cached, so the next call tries again. A rotated
 * password opens its own pool without closing the previous one, which is
 * closed once no call has used it for five minutes. A pool closed directly is
 * replaced on the next call.
@@ -50,4 +59,4 @@ declare function closeExigoPool(credentials: Pick<ExigoSqlCredentials, "host" |
 /** Closes every pool this package opened; for shutdown hooks and tests. */
 declare function closeAllExigoPools(): Promise<void>;
 //#endregion
-export { type ConnectionPool, EXIGO_SQL_DEFAULTS, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoPoolOptions, ExigoProxyError, ExigoSource, type ExigoSqlCredentials, ExigoTimeoutError, closeAllExigoPools, closeExigoPool, getExigoPool, translateExigoSqlError };
+export { type ConnectionPool, EXIGO_SQL_DEFAULTS, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, type ExigoEgressProxy, ExigoError, ExigoErrorOptions, ExigoPoolOptions, ExigoProxyError, ExigoSource, type ExigoSqlCredentials, ExigoTimeoutError, closeAllExigoPools, closeExigoPool, getExigoPool, translateExigoSqlError };

package/dist/sql.mjs

@@ -1,5 +1,7 @@
 import { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoProxyError, ExigoTimeoutError } from "./errors.mjs";
 import { assertExigoSqlCredentials } from "./credentials.mjs";
+import { normalizeEgressProxy } from "./egress-proxy.mjs";
+import { egressProxyConnector } from "./sql-tunnel.mjs";
 import { createHash } from "node:crypto";
 //#region src/sql.ts
 /**
@@ -15,6 +17,9 @@ import { createHash } from "node:crypto";
 * the first time a pool opens, so an app that only imports `./rest` never
 * loads it. In Next, list `mssql` in `serverExternalPackages` and set
 * `export const runtime = "nodejs"` on routes that query.
+*
+* With `egressProxy`, every connection is dialled through Fluid's egress
+* proxy (see `./sql-tunnel`).
 */
 const EXIGO_SQL_DEFAULTS = {
 	port: 1433,
@@ -24,9 +29,9 @@ const EXIGO_SQL_DEFAULTS = {
 	requestTimeoutMs: 3e4
 };
 /**
-* Each database holds one pool per credential fingerprint (password and TLS
-* settings). A rotation therefore never closes a pool another request is
-* using: requests that resolved the old password keep the old pool, new ones
+* Each database holds one pool per credential fingerprint (password, TLS
+* settings and egress proxy). A rotation therefore never closes a pool
+* another request is using: requests that resolved the old password keep the old pool, new ones
 * get the new pool, and a rollback finds its pool still there. A pool that
 * is not its database's most recently used one, and that no request has asked
 * for in this long, is closed and forgotten. The sweep runs on every call and,
@@ -61,14 +66,15 @@ function poolKey(credentials) {
 		credentials.username
 	]);
 }
-function fingerprint(credentials) {
+function fingerprint(credentials, proxy) {
 	return createHash("sha256").update(JSON.stringify([
 		credentials.password,
 		credentials.encrypt ?? true,
-		credentials.trustServerCertificate
+		credentials.trustServerCertificate,
+		proxy ? [proxy.url, proxy.token] : null
 	])).digest("hex");
 }
-function toMssqlConfig(credentials, options) {
+function toMssqlConfig(credentials, options, proxy) {
 	return {
 		server: credentials.host.trim(),
 		port: credentials.port ?? EXIGO_SQL_DEFAULTS.port,
@@ -85,7 +91,8 @@ function toMssqlConfig(credentials, options) {
 		options: {
 			encrypt: credentials.encrypt ?? true,
 			trustServerCertificate: credentials.trustServerCertificate,
-			enableArithAbort: true
+			enableArithAbort: true,
+			...proxy ? { connector: egressProxyConnector(proxy) } : {}
 		}
 	};
 }
@@ -129,7 +136,8 @@ function errorChain(error) {
 * such as a syntax error in a droplet's query, is returned unchanged.
 */
 function translateExigoSqlError(error) {
-	if (error instanceof ExigoError) return error;
+	const own = ownErrorIn(error);
+	if (own !== null) return own;
 	const { codes, text } = errorChain(error);
 	const code = error !== null && typeof error === "object" ? error.code : void 0;
 	const name = error instanceof Error ? error.name : "";
@@ -145,8 +153,29 @@ function translateExigoSqlError(error) {
 	if (name === "ConnectionError" || code === "ESOCKET" || code === "ECONNCLOSED") return new ExigoConnectionError(`Could not connect to Exigo's SQL Server: ${raw}`, "sql", options);
 	return error;
 }
-async function openPool(credentials, options) {
-	const pool = new (await (loadMssql())).ConnectionPool(toMssqlConfig(credentials, options));
+/** The first `ExigoError` inside mssql's and tedious's wrapping, if any. */
+function ownErrorIn(error) {
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (value, depth) => {
+		if (value === null || typeof value !== "object" || seen.has(value) || depth > 5) return null;
+		seen.add(value);
+		if (value instanceof ExigoError) return value;
+		const record = value;
+		const inner = [
+			record.originalError,
+			record.cause,
+			...Array.isArray(record.errors) ? record.errors : []
+		];
+		for (const candidate of inner) {
+			const found = visit(candidate, depth + 1);
+			if (found !== null) return found;
+		}
+		return null;
+	};
+	return visit(error, 0);
+}
+async function openPool(credentials, options, proxy) {
+	const pool = new (await (loadMssql())).ConnectionPool(toMssqlConfig(credentials, options, proxy));
 	const onError = options.onError ?? ((error) => console.warn(`[@fluid-app/exigo-connection-sdk] ${error.message}`));
 	pool.on("error", (error) => {
 		const translated = translateExigoSqlError(error);
@@ -166,8 +195,8 @@ function isUsable(pool) {
 * The open pool for these credentials, opening it on first use.
 *
 * Pools are keyed by host, port, database and username, and within that by
-* password and TLS settings. Concurrent first calls share one connect. A
-* failed connect is not cached, so the next call tries again. A rotated
+* password, TLS settings and egress proxy. Concurrent first calls share one
+* connect. A failed connect is not cached, so the next call tries again. A rotated
 * password opens its own pool without closing the previous one, which is
 * closed once no call has used it for five minutes. A pool closed directly is
 * replaced on the next call.
@@ -175,9 +204,11 @@ function isUsable(pool) {
 async function getExigoPool(credentials, options = {}) {
 	if (!credentials) throw new ExigoCredentialsError("No Exigo SQL credentials were provided.", ["sql"]);
 	assertExigoSqlCredentials(credentials);
+	const proxy = options.egressProxy ? normalizeEgressProxy(options.egressProxy) : null;
+	if (proxy && credentials.encrypt === false) throw new ExigoCredentialsError("Exigo sql.encrypt cannot be false with egressProxy; the login would cross the proxy unencrypted.", ["sql.encrypt"]);
 	const pools = cache();
 	const identity = poolKey(credentials);
-	const current = fingerprint(credentials);
+	const current = fingerprint(credentials, proxy);
 	const group = () => {
 		let entries = pools.get(identity);
 		if (entries === void 0) {
@@ -202,7 +233,7 @@ async function getExigoPool(credentials, options = {}) {
 		}
 	}
 	const entry = {
-		pool: openPool(credentials, options),
+		pool: openPool(credentials, options, proxy),
 		lastUsed: Date.now()
 	};
 	const entries = group();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/exigo-connection-sdk",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Exigo REST client, SQL pool and credential interface for Fluid droplets and Mist apps",
   "license": "UNLICENSED",
   "repository": {