feat: US-027 - Add TLS database connection e2e-docker fixtures

Implement tls.connect() bridge for TLS socket upgrade, enabling SSL-encrypted
database connections through the sandbox. The pg-ssl fixture validates that
Postgres SSL connections work end-to-end via the sandbox's net + tls bridge.

Bridge changes:
- Add NetSocketUpgradeTlsRaw bridge contract for TLS socket upgrade
- Add tls module to sandbox (connect, TLSSocket, createSecureContext)
- Host-side wraps existing net.Socket with Node.js tls.TLSSocket
- Forward end/close events to wrapped raw socket (pg relies on this)
- Wire tls module into require-setup for require('tls') resolution

Infrastructure:
- Custom postgres-ssl Dockerfile with self-signed certificate
- Postgres container now runs with SSL enabled (all pg fixtures unaffected)
- New pg-ssl fixture: connects with ssl:{rejectUnauthorized:false}, queries
  pg_stat_ssl to verify encryption, runs CRUD operations through TLS

Author: NathanFlurry

packages/secure-exec-core/isolate-runtime/src/inject/require-setup.ts

@@ -1492,6 +1492,14 @@
           return _netModule;
         }
 
+        // Special handling for tls module
+        if (name === 'tls') {
+          if (__internalModuleCache['tls']) return __internalModuleCache['tls'];
+          __internalModuleCache['tls'] = _tlsModule;
+          _debugRequire('loaded', name, 'tls-special');
+          return _tlsModule;
+        }
+
         // Special handling for os module
         if (name === 'os') {
           if (__internalModuleCache['os']) return __internalModuleCache['os'];

packages/secure-exec-core/src/bridge/network.ts

@@ -22,6 +22,7 @@ import type {
 	NetSocketWriteRawBridgeRef,
 	NetSocketEndRawBridgeRef,
 	NetSocketDestroyRawBridgeRef,
+	NetSocketUpgradeTlsRawBridgeRef,
 } from "../shared/bridge-contract.js";
 
 // Declare host bridge References
@@ -67,6 +68,10 @@ declare const _netSocketDestroyRaw:
   | NetSocketDestroyRawBridgeRef
   | undefined;
 
+declare const _netSocketUpgradeTlsRaw:
+  | NetSocketUpgradeTlsRawBridgeRef
+  | undefined;
+
 declare const _registerHandle:
   | RegisterHandleBridgeFn
   | undefined;
@@ -1957,7 +1962,8 @@ class NetSocket {
   bytesRead = 0;
   bytesWritten = 0;
   private _listeners: Record<string, EventListener[]> = {};
-  private _socketId = -1;
+  /** @internal socket ID shared with TLS upgrade bridge */
+  _socketId = -1;
   private _connectHost = "";
   private _connectPort = 0;
 
@@ -2213,6 +2219,7 @@ function onNetSocketDispatch(socketId: number, type: string, data: string): void
     case "end": socket._onEnd(); break;
     case "error": socket._onError(data); break;
     case "close": socket._onClose(data === "1"); break;
+    case "secureConnect": socket.emit("secureConnect"); break;
   }
 }
 
@@ -2248,12 +2255,101 @@ export const net = {
   isIPv6(input: string): boolean { return netIsIP(input) === 6; },
 };
 
+// ----------------------------------------------------------------
+// tls module — TLS socket upgrade bridge
+// ----------------------------------------------------------------
+
+/** TLS socket that wraps an existing NetSocket after host-side TLS upgrade. */
+class TLSSocket extends NetSocket {
+  encrypted = true;
+  authorized = false;
+  authorizationError: string | null = null;
+  alpnProtocol: string | false = false;
+  private _wrappedSocket: NetSocket | null = null;
+
+  constructor(originalSocket: NetSocket) {
+    super();
+    this._wrappedSocket = originalSocket;
+    // Copy connection state from original socket
+    this.remoteAddress = originalSocket.remoteAddress;
+    this.remotePort = originalSocket.remotePort;
+    this.remoteFamily = originalSocket.remoteFamily;
+    this.localAddress = originalSocket.localAddress;
+    this.localPort = originalSocket.localPort;
+    this.connecting = false;
+    this.pending = false;
+    this.readyState = "open";
+    // Share the same socketId — bridge events route here after upgrade
+    this._socketId = originalSocket._socketId;
+    // Copy private connect info so _cleanup unregisters the correct handle
+    (this as Record<string, unknown>)._connectHost = (originalSocket as Record<string, unknown>)._connectHost;
+    (this as Record<string, unknown>)._connectPort = (originalSocket as Record<string, unknown>)._connectPort;
+    netSocketInstances.set(this._socketId, this);
+  }
+
+  _onSecureConnect(): void {
+    this.authorized = true;
+    this.emit("secureConnect");
+  }
+
+  // Forward end/close to the wrapped raw socket — Node.js tls.TLSSocket
+  // closes the underlying socket, which fires its 'close' event. Libraries
+  // like pg rely on the original socket's 'close' listener to detect shutdown.
+  _onEnd(): void {
+    super._onEnd();
+    if (this._wrappedSocket) this._wrappedSocket._onEnd();
+  }
+
+  _onClose(hadError: boolean): void {
+    super._onClose(hadError);
+    if (this._wrappedSocket) {
+      this._wrappedSocket._onClose(hadError);
+      this._wrappedSocket = null;
+    }
+  }
+}
+
+export const tlsModule = {
+  TLSSocket: TLSSocket as unknown as typeof import("tls").TLSSocket,
+  connect(options: Record<string, unknown>): NetSocket {
+    const existingSocket = options.socket as NetSocket | undefined;
+    if (!existingSocket || existingSocket._socketId < 0) {
+      throw new Error("tls.connect requires an existing connected socket via options.socket");
+    }
+
+    // Create TLS socket wrapper on sandbox side
+    const tlsSocket = new TLSSocket(existingSocket);
+
+    if (typeof _netSocketUpgradeTlsRaw === "undefined") {
+      Promise.resolve().then(() => {
+        tlsSocket._onError("tls.connect requires NetworkAdapter TLS support");
+      });
+      return tlsSocket;
+    }
+
+    // Tell host to wrap the underlying TCP socket with TLS
+    _netSocketUpgradeTlsRaw.applySync(undefined, [
+      existingSocket._socketId,
+      JSON.stringify({
+        rejectUnauthorized: options.rejectUnauthorized ?? true,
+        servername: options.servername,
+      }),
+    ]);
+
+    return tlsSocket;
+  },
+  createSecureContext(_options?: Record<string, unknown>): Record<string, unknown> {
+    return {};
+  },
+};
+
 // Export modules and make them available as globals for require()
 exposeCustomGlobal("_httpModule", http);
 exposeCustomGlobal("_httpsModule", https);
 exposeCustomGlobal("_http2Module", http2);
 exposeCustomGlobal("_dnsModule", dns);
 exposeCustomGlobal("_netModule", net);
+exposeCustomGlobal("_tlsModule", tlsModule);
 exposeCustomGlobal("_httpServerDispatch", dispatchServerRequest);
 exposeCustomGlobal("_httpServerUpgradeDispatch", dispatchUpgradeRequest);
 exposeCustomGlobal("_upgradeSocketData", onUpgradeSocketData);
@@ -2280,6 +2376,7 @@ export default {
   https,
   http2,
   net,
+  tls: tlsModule,
   IncomingMessage,
   ClientRequest,
 };

packages/secure-exec-core/src/generated/isolate-runtime.ts

@@ -75,6 +75,7 @@ export const HOST_BRIDGE_GLOBAL_KEYS = {
 	netSocketWriteRaw: "_netSocketWriteRaw",
 	netSocketEndRaw: "_netSocketEndRaw",
 	netSocketDestroyRaw: "_netSocketDestroyRaw",
+	netSocketUpgradeTlsRaw: "_netSocketUpgradeTlsRaw",
 	ptySetRawMode: "_ptySetRawMode",
 	processConfig: "_processConfig",
 	osConfig: "_osConfig",
@@ -101,6 +102,7 @@ export const RUNTIME_BRIDGE_GLOBAL_KEYS = {
 	upgradeSocketData: "_upgradeSocketData",
 	upgradeSocketEnd: "_upgradeSocketEnd",
 	netModule: "_netModule",
+	tlsModule: "_tlsModule",
 	netSocketDispatch: "_netSocketDispatch",
 	fsFacade: "_fs",
 	requireFrom: "_requireFrom",
@@ -273,6 +275,9 @@ export type NetSocketWriteRawBridgeRef = BridgeApplySyncRef<[number, string], vo
 export type NetSocketEndRawBridgeRef = BridgeApplySyncRef<[number], void>;
 export type NetSocketDestroyRawBridgeRef = BridgeApplySyncRef<[number], void>;
 
+// TLS socket upgrade boundary contract.
+export type NetSocketUpgradeTlsRawBridgeRef = BridgeApplySyncRef<[number, string], void>;
+
 // PTY boundary contracts.
 export type PtySetRawModeBridgeRef = BridgeApplySyncRef<[boolean], void>;
 

packages/secure-exec-core/src/shared/bridge-contract.ts

@@ -295,6 +295,7 @@ export function wrapNetworkAdapter(
 		netSocketWrite: adapter.netSocketWrite?.bind(adapter),
 		netSocketEnd: adapter.netSocketEnd?.bind(adapter),
 		netSocketDestroy: adapter.netSocketDestroy?.bind(adapter),
+		netSocketUpgradeTls: adapter.netSocketUpgradeTls?.bind(adapter),
 	};
 }
 

packages/secure-exec-core/src/shared/permissions.ts

@@ -258,6 +258,18 @@ export interface NetworkAdapter {
 	netSocketEnd?(socketId: number): void;
 	/** Destroy a TCP socket. */
 	netSocketDestroy?(socketId: number): void;
+	/** Upgrade an existing TCP socket to TLS. */
+	netSocketUpgradeTls?(
+		socketId: number,
+		optionsJson: string,
+		callbacks: {
+			onData: (dataBase64: string) => void;
+			onEnd: () => void;
+			onError: (message: string) => void;
+			onClose: (hadError: boolean) => void;
+			onSecureConnect: () => void;
+		},
+	): void;
 }
 
 export interface PermissionDecision {

packages/secure-exec-core/src/types.ts

@@ -1656,10 +1656,24 @@ export async function setupRequire(
 			},
 		);
 
+		const netSocketUpgradeTlsRef = new ivm.Reference(
+			(socketId: number, optionsJson: string): void => {
+				checkBridgeBudget(deps);
+				adapter.netSocketUpgradeTls?.(socketId, optionsJson, {
+					onData: (dataBase64) => dispatchNetEvent(socketId, "data", dataBase64),
+					onEnd: () => dispatchNetEvent(socketId, "end", ""),
+					onError: (message) => dispatchNetEvent(socketId, "error", message),
+					onClose: (hadError) => dispatchNetEvent(socketId, "close", hadError ? "1" : "0"),
+					onSecureConnect: () => dispatchNetEvent(socketId, "secureConnect", ""),
+				});
+			},
+		);
+
 		await jail.set(HOST_BRIDGE_GLOBAL_KEYS.netSocketConnectRaw, netSocketConnectRef);
 		await jail.set(HOST_BRIDGE_GLOBAL_KEYS.netSocketWriteRaw, netSocketWriteRef);
 		await jail.set(HOST_BRIDGE_GLOBAL_KEYS.netSocketEndRaw, netSocketEndRef);
 		await jail.set(HOST_BRIDGE_GLOBAL_KEYS.netSocketDestroyRaw, netSocketDestroyRef);
+		await jail.set(HOST_BRIDGE_GLOBAL_KEYS.netSocketUpgradeTlsRaw, netSocketUpgradeTlsRef);
 	}
 
 	// Set up PTY setRawMode bridge ref when stdin is a TTY

packages/secure-exec-node/src/bridge-setup.ts

@@ -4,6 +4,7 @@ import * as net from "node:net";
 import type { AddressInfo } from "node:net";
 import * as http from "node:http";
 import * as https from "node:https";
+import * as tls from "node:tls";
 import type { Server as HttpServer } from "node:http";
 import * as zlib from "node:zlib";
 import {
@@ -503,6 +504,35 @@ export function createDefaultNetworkAdapter(options?: {
 			}
 		},
 
+		// TLS upgrade: wrap existing TCP socket with TLS
+		netSocketUpgradeTls(socketId, optionsJson, callbacks) {
+			const socket = upgradeSockets.get(socketId);
+			if (!socket) return;
+
+			const opts = JSON.parse(optionsJson);
+			// Remove bridge event listeners from the raw TCP socket so encrypted
+			// data doesn't leak through the old callbacks. Only remove specific
+			// event types to preserve internal Node.js stream listeners.
+			for (const ev of ["data", "end", "error", "close", "connect"]) {
+				socket.removeAllListeners(ev);
+			}
+
+			const tlsSocket = tls.connect({
+				socket: socket as net.Socket,
+				rejectUnauthorized: opts.rejectUnauthorized ?? true,
+				servername: opts.servername,
+			});
+
+			// Wire bridge callbacks to the TLS socket (decrypted data)
+			tlsSocket.on("data", (chunk) => callbacks.onData(chunk.toString("base64")));
+			tlsSocket.on("end", () => callbacks.onEnd());
+			tlsSocket.on("error", (err) => callbacks.onError(err.message));
+			tlsSocket.on("close", (hadError) => callbacks.onClose(hadError));
+			tlsSocket.on("secureConnect", () => callbacks.onSecureConnect());
+
+			upgradeSockets.set(socketId, tlsSocket);
+		},
+
 		async fetch(url, options) {
 			// SSRF: validate initial URL and manually follow redirects
 			// Allow loopback fetch to sandbox-owned server ports

packages/secure-exec-node/src/driver.ts

@@ -157,16 +157,23 @@ describe.skipIf(skipReason)("e2e-docker", () => {
 			return;
 		}
 
-		// Build SSH image
+		// Build custom images
 		const sshdDockerfile = path.join(
 			FIXTURES_ROOT,
 			"dockerfiles",
 			"sshd.Dockerfile",
 		);
 		buildImage(sshdDockerfile, "secure-exec-test-sshd");
 
+		const pgSslDockerfile = path.join(
+			FIXTURES_ROOT,
+			"dockerfiles",
+			"postgres-ssl.Dockerfile",
+		);
+		buildImage(pgSslDockerfile, "secure-exec-test-postgres-ssl");
+
 		// Start containers (startContainer is synchronous — sequential start)
-		const pg = startContainer("postgres:16-alpine", {
+		const pg = startContainer("secure-exec-test-postgres-ssl", {
 			ports: { 5432: 0 },
 			env: {
 				POSTGRES_USER: "testuser",
@@ -176,6 +183,12 @@ describe.skipIf(skipReason)("e2e-docker", () => {
 			healthCheck: ["pg_isready", "-U", "testuser", "-d", "testdb"],
 			healthCheckTimeout: 30_000,
 			args: ["--tmpfs", "/var/lib/postgresql/data"],
+			// Enable SSL with self-signed certificate from custom image
+			command: [
+				"-c", "ssl=on",
+				"-c", "ssl_cert_file=/var/lib/postgresql/server.crt",
+				"-c", "ssl_key_file=/var/lib/postgresql/server.key",
+			],
 		});
 
 		const mysql = startContainer("mysql:8.0", {

packages/secure-exec/tests/e2e-docker.test.ts

@@ -0,0 +1,10 @@
+FROM postgres:16-alpine
+# Generate self-signed certificate for SSL testing
+RUN apk add --no-cache openssl \
+ && openssl req -new -x509 -days 365 -nodes \
+    -out /var/lib/postgresql/server.crt \
+    -keyout /var/lib/postgresql/server.key \
+    -subj "/CN=localhost" \
+ && chown postgres:postgres /var/lib/postgresql/server.crt /var/lib/postgresql/server.key \
+ && chmod 600 /var/lib/postgresql/server.key
+EXPOSE 5432