feat(NODE-7546): add HTTP Proxy support for QE & CSFLE by tadjik1 · Pull Request #5007 · mongodb/node-mongodb-native

tadjik1 · 2026-07-17T11:34:16Z

Description

Summary of Changes

Adds kmsConnectCallback to AutoEncryptionOptions and ClientEncryptionOptions. When provided, the driver invokes the callback to establish the TCP connection to a KMS host instead of opening the socket itself, then wraps the returned socket with TLS using the KMS provider's configured TLS options. The primary use case is routing KMS requests through an HTTP proxy via the HTTP CONNECT method, which the existing SOCKS5 proxyOptions does not cover.

Spec: mongodb/specifications#1956

Release Highlight

HTTP proxy support for KMS requests in CSFLE and Queryable Encryption

In-use encryption can now route KMS requests through an HTTP proxy. Set kmsConnectCallback on your ClientEncryption or auto-encryption options to control how the driver connects to a KMS host. The callback receives the target host and port and returns a connected socket (for example, a tunnel
opened with HTTP CONNECT); the driver then performs the KMS TLS handshake over that socket using the provider's configured TLS options. This unblocks CSFLE and Queryable Encryption in environments that require an HTTP forward proxy for outbound KMS traffic, which the existing SOCKS5 proxyOptions does not cover.

const clientEncryption = new ClientEncryption(keyVaultClient, {
  keyVaultNamespace,
  kmsProviders,
  // Establish the KMS connection through your HTTP proxy; the driver adds TLS.
  kmsConnectCallback: ({ host, port }) => connectThroughHttpProxy(host, port)
});

Double check the following

Lint is passing (npm run check:lint)
Self-review completed using the steps outlined here
PR title follows the correct format: type(NODE-xxxx)[!]: description
- Example: feat(NODE-1234)!: rewriting everything in coffeescript
Changes are covered by tests
New TODOs have a related JIRA ticket

Copilot

Pull request overview

Adds support for customizing how KMS sockets are established for CSFLE/Queryable Encryption by introducing a kmsConnectCallback API (enabling HTTP CONNECT proxy tunneling) and wiring it through the CSFLE state machine, with accompanying unit + prose integration coverage.

Changes:

Introduces KMSConnectCallback (and related TLS/socket option types) in a new kms_options module and exports them from the public index.
Wires kmsConnectCallback through AutoEncrypter/ClientEncryption into the StateMachine KMS request path (including CSOT-aware behavior) and enforces mutual exclusivity with proxyOptions.
Adds unit tests and a new prose integration test (Prose test 28) validating callback invocation, proxy tunneling behavior, and timeout/error propagation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
test/unit/client-side-encryption/state_machine.test.ts	Adds unit coverage for CSOT behavior and new `kmsConnectCallback` socket establishment + timeout semantics.
test/unit/client-side-encryption/client_encryption.test.ts	Adds unit coverage for `proxyOptions` vs `kmsConnectCallback` conflict validation in `ClientEncryption`.
test/unit/client-side-encryption/auto_encrypter.test.ts	Adds unit coverage for `proxyOptions` vs `kmsConnectCallback` conflict validation in `AutoEncrypter`.
test/mongodb_all.ts	Re-exports new `kms_options` types for tests.
test/integration/client-side-encryption/client_side_encryption.prose.28.kms_connect_callback.test.ts	Adds prose integration coverage for KMS connect callback through HTTP/HTTPS proxy.
src/index.ts	Publicly exports `kms_options` types and removes those type exports from `state_machine`.
src/client-side-encryption/state_machine.ts	Implements `kmsConnectCallback` support and revises CSOT timeout handling for KMS requests.
src/client-side-encryption/kms_options.ts	New module defining public KMS TLS/socket option types and `KMSConnectCallback` contract.
src/client-side-encryption/client_encryption.ts	Stores/validates `kmsConnectCallback` and passes it into `StateMachine`.
src/client-side-encryption/auto_encrypter.ts	Stores/validates `kmsConnectCallback` and passes it into `StateMachine`.

…e test

tadjik1 · 2026-07-17T12:37:34Z

+      const timeoutMS = Number.isFinite(remainingTimeMS) ? remainingTimeMS : undefined;
+      kmsRequestTimeout = timeoutMS ? Timeout.expires(timeoutMS) : undefined;
+      await (kmsRequestTimeout
+        ? Promise.race([willResolveKmsRequest, kmsRequestTimeout])


Note: .race() instead of .all() since the timeout is throwing on expire. This is fix for the pre-existing bug (test coverage also added).

tadjik1 · 2026-07-17T12:45:55Z

  }
 }

-/**


This is small refactoring, instead of adding one more Options type into StateMachine code I have extracted it into separate module kms_options.ts.

…k is going to be used

nbbeeken

apologies for the piecemeal review, noticed this on the second read. LGTM either way

dariakp

Note that this PR must wait for mongodb/specifications#1956 to merge before it can be fully reviewed and merged. (Will resolve this comment once this PR is unblocked).

PavelSafronov · 2026-07-20T20:07:30Z

+          host: socketOptions.host,
+          port: socketOptions.port,
+          timeoutMS,
+          signal: controller.signal


Should the signal also include options.signal? That's an optional signal that is honored elsewhere (line 450), but we're ignore it here.

Thanks, addressed!

PavelSafronov · 2026-07-20T20:13:50Z

+            const timeoutError = new MongoOperationTimeoutError('KMS request timed out');
+            // Abort with the timeout error as the reason so the callback sees it on `signal.reason`.
+            controller.abort(timeoutError);
+            throw timeoutError;


If connectPromise eventually (after timeout) returns a socket, that socket will never be closed. Consider something like to close the socket:

connectPromise.then( sock => { if (controller.signal.aborted) sock.destroy(); }, () => {} // nothing to cleanup );

THanks! Added.

PavelSafronov

New changes look good, approving and moving to team review.

johnmtll · 2026-07-29T00:26:40Z

+        const timeoutMS = Number.isFinite(remainingTimeMS) ? remainingTimeMS : undefined;
+        const controller = new AbortController();
+        // Forward the operation's own abort signal so aborting the operation also aborts the callback.
+        const forwardAbort = addAbortListener(options?.signal, function () {


Should we have a guard here to protect against already-aborted signals? E.g: something like:
options?.signal?.throwIfAborted() before this.

Yes, great catch. I updated all paths to respect already expired timeout (test coverage added as well).

johnmtll · 2026-07-29T00:29:18Z

-      if (this.options.proxyOptions && this.options.proxyOptions.proxyHost) {
+      if (this.options.kmsConnectCallback) {
+        const remainingTimeMS = options?.timeoutContext?.csotEnabled()
+          ? options.timeoutContext.getRemainingTimeMSOrThrow('KMS request timed out')


Nit: Can we include the timeoutMS in the throw reason? The default message includes it, so technically this is less informative.

Thanks, added.

johnmtll · 2026-07-29T00:48:18Z

+        const timeout = timeoutMS ? Timeout.expires(timeoutMS) : undefined;
+        try {
+          socketOptions.socket = timeout
+            ? await Promise.race([connectPromise, timeout])


Idea: I'm noticing here we're exclusively relying on the user to unblock (either with a supplied CSOT timeout or by resolving from kmsConnectCallback()). The timeout here can be very long (or infinite, with a timeoutMS of 0). This makes me worry about open handles (http requests) dangling beyond the lifetime of parent objects (e.g: a client closure). Probably a separate PR, but I think it's worth considering.

Great call, I will request spec owners to update spec, I guess the legacy timeout might fit here just fine.

feat(NODE-7546): add HTTP Proxy support for QE & CSFLE

54a5908

tadjik1 requested a review from Copilot July 17, 2026 11:35

Copilot started reviewing on behalf of tadjik1 July 17, 2026 11:35 View session

Copilot AI reviewed Jul 17, 2026

View reviewed changes

Comment thread src/client-side-encryption/state_machine.ts Outdated

cover potential expired timeouts, fix bug with shared library in pros…

bd07fa6

…e test

tadjik1 commented Jul 17, 2026

View reviewed changes

tadjik1 marked this pull request as ready for review July 17, 2026 14:28

tadjik1 requested a review from a team as a code owner July 17, 2026 14:28

tadjik1 requested a review from nbbeeken July 17, 2026 14:28

nbbeeken reviewed Jul 17, 2026

View reviewed changes

Comment thread src/client-side-encryption/kms_options.ts Outdated

loosen the type, improve JSDoc to explain how Duplex from the callbac…

2362f00

…k is going to be used

dariakp added the Blocked Blocked on other work label Jul 17, 2026

nbbeeken previously approved these changes Jul 17, 2026

View reviewed changes

Comment thread src/client-side-encryption/state_machine.ts

dariakp requested changes Jul 17, 2026

View reviewed changes

provide reason for abort signal

aae293b

tadjik1 dismissed nbbeeken’s stale review via aae293b July 20, 2026 10:47

dariakp marked this pull request as draft July 20, 2026 14:54

dariakp requested a review from PavelSafronov July 20, 2026 14:55

PavelSafronov reviewed Jul 20, 2026

View reviewed changes

tadjik1 mentioned this pull request Jul 21, 2026

DRIVERS-2920 CSFLE/QE Support for HTTP Proxies mongodb/specifications#1956

Merged

tadjik1 added 3 commits July 22, 2026 15:16

add doc example; improve operation timeouts handling;

3deb6c0

Merge branch 'main' into NODE-7546

92c0c38

Merge branch 'main' into NODE-7546

4462853

tadjik1 removed the Blocked Blocked on other work label Jul 28, 2026

tadjik1 marked this pull request as ready for review July 28, 2026 11:17

tadjik1 requested review from PavelSafronov, dariakp and nbbeeken July 28, 2026 11:17

sync prose test

87673fd

nbbeeken previously approved these changes Jul 28, 2026

View reviewed changes

PavelSafronov previously approved these changes Jul 28, 2026

View reviewed changes

PavelSafronov self-assigned this Jul 28, 2026

PavelSafronov added the Team Review Needs review from team label Jul 28, 2026

johnmtll requested changes Jul 29, 2026

View reviewed changes

guard aborted signal and include timeoutMS in KMS timeout errors

6f3140c

tadjik1 dismissed stale reviews from PavelSafronov and nbbeeken via 6f3140c July 29, 2026 11:09

tadjik1 requested review from PavelSafronov and johnmtll July 29, 2026 12:01

                 }
               }
-              /**

Uh oh!

Conversation

tadjik1 commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

Release Highlight

HTTP proxy support for KMS requests in CSFLE and Queryable Encryption

Double check the following

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nbbeeken left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dariakp left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PavelSafronov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

tadjik1 commented Jul 17, 2026 •

edited

Loading

dariakp left a comment •

edited

Loading