@depup/mongodb 7.5.0-depup.7 → 7.6.0-depup.0

package/mongodb.d.ts

@@ -25,6 +25,7 @@ import { EventEmitter } from 'events';
 import type { Socket } from 'net';
 import type { TcpNetConnectOpts } from 'net';
 import type * as os from 'os';
+import type { Duplex } from 'stream';
 import { Readable } from 'stream';
 import { Writable } from 'stream';
 import type { ConnectionOptions as ConnectionOptions_2 } from 'tls';
@@ -277,11 +278,6 @@ export declare interface AbstractCursorOptions extends BSONSerializeOptions {
     maxAwaitTimeMS?: number;
     /**
      * Comment to apply to the operation.
-     *
-     * In server versions pre-4.4, 'comment' must be string.  A server
-     * error will be thrown if any other type is provided.
-     *
-     * In server versions 4.4 and above, 'comment' can be any valid BSON type.
      */
     comment?: unknown;
     /**
@@ -821,6 +817,12 @@ export declare interface AutoEncryptionOptions {
     proxyOptions?: ProxyOptions;
     /** The TLS options to use connecting to the KMS provider */
     tlsOptions?: CSFLEKMSTlsOptions;
+    /**
+     * A callback that establishes the socket used to connect to a KMS host, e.g. to route KMS
+     * requests through an HTTP proxy via the HTTP CONNECT method. Mutually exclusive with `proxyOptions`.
+     * See {@link KMSConnectCallback} for a usage example.
+     */
+    kmsConnectCallback?: KMSConnectCallback;
 }
 
 /** @public **/
@@ -933,6 +935,7 @@ export declare class Batch<T = Document> {
     originalIndexes: number[];
     batchType: BatchType;
     operations: T[];
+    serializedOperations: Uint8Array[];
     size: number;
     sizeBytes: number;
     constructor(batchType: BatchType, originalZeroIndex: number);
@@ -1047,7 +1050,7 @@ export declare abstract class BulkOperationBase {
      * // Add a replaceOne
      * bulkOp.find({ i: 9 }).replaceOne({writeConcern: { j: 10 }});
      *
-     * // Update using a pipeline (requires Mongodb 4.2 or higher)
+     * // Update using a pipeline
      * bulk.find({ k: 11, y: { $exists: true }, z: { $exists: true } }).updateOne([
      *   { $set: { total: { $sum: [ '$y', '$z' ] } } }
      * ]);
@@ -1793,6 +1796,7 @@ export declare class ClientEncryption {
     /* Excluded from this release type: _keyVaultClient */
     /* Excluded from this release type: _proxyOptions */
     /* Excluded from this release type: _tlsOptions */
+    /* Excluded from this release type: _kmsConnectCallback */
     /* Excluded from this release type: _kmsProviders */
     /* Excluded from this release type: _timeoutMS */
     /* Excluded from this release type: _mongoCrypt */
@@ -2186,6 +2190,12 @@ export declare interface ClientEncryptionOptions {
      * TLS options for kms providers to use.
      */
     tlsOptions?: CSFLEKMSTlsOptions;
+    /**
+     * A callback that establishes the socket used to connect to a KMS host, e.g. to route KMS
+     * requests through an HTTP proxy via the HTTP CONNECT method. Mutually exclusive with `proxyOptions`.
+     * See {@link KMSConnectCallback} for a usage example.
+     */
+    kmsConnectCallback?: KMSConnectCallback;
     /**
      * Sets the expiration time for the DEK in the cache in milliseconds. Defaults to 60000. 0 means no timeout.
      */
@@ -3267,7 +3277,7 @@ export declare class CommandFailedEvent {
     connectionId?: string | number;
     /**
      * Server generated connection id
-     * Distinct from the connection id and is returned by the hello or legacy hello response as "connectionId" from the server on 4.2+.
+     * Distinct from the connection id and is returned by the hello or legacy hello response as "connectionId" from the server.
      */
     serverConnectionId: bigint | null;
     requestId: number;
@@ -3295,11 +3305,6 @@ export declare interface CommandOperationOptions extends OperationOptions, Write
     maxTimeMS?: number;
     /**
      * Comment to apply to the operation.
-     *
-     * In server versions pre-4.4, 'comment' must be string.  A server
-     * error will be thrown if any other type is provided.
-     *
-     * In server versions 4.4 and above, 'comment' can be any valid BSON type.
      */
     comment?: unknown;
     dbName?: string;
@@ -3326,7 +3331,7 @@ export declare class CommandStartedEvent {
     /**
      * Server generated connection id
      * Distinct from the connection id and is returned by the hello or legacy hello response as "connectionId"
-     * from the server on 4.2+.
+     * from the server.
      */
     serverConnectionId: bigint | null;
     serviceId?: ObjectId;
@@ -3346,7 +3351,7 @@ export declare class CommandSucceededEvent {
     connectionId?: string | number;
     /**
      * Server generated connection id
-     * Distinct from the connection id and is returned by the hello or legacy hello response as "connectionId" from the server on 4.2+.
+     * Distinct from the connection id and is returned by the hello or legacy hello response as "connectionId" from the server.
      */
     serverConnectionId: bigint | null;
     requestId: number;
@@ -3730,7 +3735,7 @@ export declare interface CreateIndexesOptions extends Omit<CommandOperationOptio
     expireAfterSeconds?: number;
     /** Allows users to configure the storage engine on a per-index basis when creating an index. (MongoDB 3.0 or higher) */
     storageEngine?: Document;
-    /** (MongoDB 4.4. or higher) Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes. */
+    /** Specifies how many data-bearing members of a replica set, including the primary, must complete the index builds successfully before the primary marks the indexes as ready. This option accepts the same values for the "w" field in a write concern plus "votingMembers", which indicates all voting data-bearing nodes. */
     commitQuorum?: number | string;
     /** Specifies the index version number, either 0 or 1. */
     version?: number;
@@ -3746,7 +3751,7 @@ export declare interface CreateIndexesOptions extends Omit<CommandOperationOptio
     max?: number;
     bucketSize?: number;
     wildcardProjection?: Document;
-    /** Specifies that the index should exist on the target collection but should not be used by the query planner when executing operations. (MongoDB 4.4 or higher) */
+    /** Specifies that the index should exist on the target collection but should not be used by the query planner when executing operations. */
     hidden?: boolean;
 }
 
@@ -5303,6 +5308,58 @@ export declare interface KMIPKMSProviderConfiguration {
     endpoint?: string;
 }
 
+/**
+ * @public
+ *
+ * A callback that establishes the connection to a KMS host.
+ *
+ * When provided on `AutoEncryptionOptions` or `ClientEncryptionOptions`, the driver invokes this
+ * callback instead of connecting to the KMS host itself, passing the target `host` and `port`. The
+ * callback MUST return a `Duplex` stream connected to the KMS host, either directly or tunneled
+ * through a proxy; a `net.Socket` satisfies this, as does any other `Duplex`. The returned stream is
+ * passed to Node.js' `tls.connect()` as its `socket`, and the driver performs the KMS host's TLS
+ * handshake over it using the KMS provider's configured TLS options. The callback therefore MUST NOT
+ * perform the KMS host's TLS handshake itself, though it MAY use TLS for its own transport, e.g. when
+ * connecting to an HTTPS proxy. This enables routing KMS requests through an HTTP proxy via the HTTP
+ * CONNECT method.
+ *
+ * When the operation has a client-side operation timeout (CSOT) configured, `timeoutMS` is the
+ * remaining time budget in milliseconds; it is `undefined` otherwise. The `signal` aborts when the
+ * connection attempt exceeds that budget; the callback should stop connecting and reject when it fires.
+ *
+ * @example <caption>Route KMS requests through an HTTP proxy using the HTTP CONNECT method</caption>
+ * ```ts
+ * import * as net from 'net';
+ *
+ * const kmsConnectCallback: KMSConnectCallback = ({ host, port, signal }) =>
+ *   new Promise((resolve, reject) => {
+ *     // Open a plain connection to the proxy, not to the KMS host.
+ *     const socket = net.connect({ host: 'proxy.example.com', port: 8080, signal });
+ *     socket.once('error', reject);
+ *     socket.once('connect', () => {
+ *       // Ask the proxy to tunnel to the KMS host, then hand the socket back for the driver's TLS.
+ *       socket.write(`CONNECT ${host}:${port} HTTP/1.1\r\nHost: ${host}:${port}\r\n\r\n`);
+ *       socket.once('data', chunk => {
+ *         if (chunk.toString('utf8').startsWith('HTTP/1.1 200')) resolve(socket);
+ *         else reject(new Error('Proxy refused the CONNECT request'));
+ *       });
+ *     });
+ *   });
+ *
+ * const clientEncryption = new ClientEncryption(keyVaultClient, {
+ *   keyVaultNamespace,
+ *   kmsProviders,
+ *   kmsConnectCallback
+ * });
+ * ```
+ */
+export declare type KMSConnectCallback = (options: {
+    host: string;
+    port: number;
+    timeoutMS?: number;
+    signal: AbortSignal;
+}) => Promise<Duplex>;
+
 /**
  * @public
  * Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
@@ -5361,11 +5418,11 @@ export declare class ListCollectionsCursor<T extends Pick<CollectionInfo, 'name'
 
 /** @public */
 export declare interface ListCollectionsOptions extends Omit<CommandOperationOptions, 'writeConcern'>, Abortable {
-    /** Since 4.0: If true, will only return the collection name in the response, and will omit additional info */
+    /** If true, will only return the collection name in the response, and will omit additional info */
     nameOnly?: boolean;
-    /** Since 4.0: If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */
+    /** If true and nameOnly is true, allows a user without the required privilege (i.e. listCollections action on the database) to run the command when access control is enforced. */
     authorizedCollections?: boolean;
-    /** The batchSize for the returned command cursor or if pre 2.8 the systems batch collection */
+    /** The batchSize for the returned command cursor */
     batchSize?: number;
     /* Excluded from this release type: timeoutMode */
     /* Excluded from this release type: timeoutContext */
@@ -8889,7 +8946,7 @@ export { UUID }
 
 /** @public */
 export declare interface ValidateCollectionOptions extends Omit<CommandOperationOptions, 'rawData'> {
-    /** Validates a collection in the background, without interrupting read or write traffic (only in MongoDB 4.4+) */
+    /** Validates a collection in the background, without interrupting read or write traffic */
     background?: boolean;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depup/mongodb",
-  "version": "7.5.0-depup.7",
+  "version": "7.6.0-depup.0",
   "description": "The official MongoDB driver for Node.js (with updated dependencies)",
   "main": "lib/index.js",
   "files": [
@@ -32,8 +32,8 @@
     "email": "dbx-node@mongodb.com"
   },
   "dependencies": {
-    "@mongodb-js/saslprep": "^1.4.12",
-    "bson": "^7.3.1",
+    "@mongodb-js/saslprep": "^1.5.0",
+    "bson": "^7.3.2",
     "mongodb-connection-string-url": "^7.0.2"
   },
   "peerDependencies": {
@@ -109,7 +109,7 @@
     "semver": "^7.7.2",
     "sinon": "^18.0.1",
     "sinon-chai": "^4.0.1",
-    "snappy": "^7.3.2",
+    "snappy": "7.3.3",
     "socks": "^2.8.7",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
@@ -164,6 +164,7 @@
     "check:csfle": "npm run build:bundle && nyc mocha --config test/mocha_mongodb.js test/integration/client-side-encryption",
     "check:snappy": "npm run build:bundle && nyc mocha test/unit/assorted/snappy.test.js",
     "check:x509": "npm run build:bundle && nyc mocha test/manual/x509_auth.test.ts",
+    "check:sfp": "npm run build:bundle && nyc mocha test/manual/sfp.test.ts",
     "mocha:debug": "npm run build:bundle && node --inspect --enable-source-maps --no-experimental-strip-types ./node_modules/mocha/bin/mocha.js",
     "build:bundle": "npm run bundle:driver && npm run bundle:types && npm run build:runtime-barrel",
     "build:runtime-barrel": "node etc/build-runtime-barrel.mjs",
@@ -190,11 +191,11 @@
     "changes": {
       "@mongodb-js/saslprep": {
         "from": "^1.4.11",
-        "to": "^1.4.12"
+        "to": "^1.5.0"
       },
       "bson": {
         "from": "^7.2.0",
-        "to": "^7.3.1"
+        "to": "^7.3.2"
       },
       "mongodb-connection-string-url": {
         "from": "^7.0.1",
@@ -203,8 +204,8 @@
     },
     "depsUpdated": 3,
     "originalPackage": "mongodb",
-    "originalVersion": "7.5.0",
-    "processedAt": "2026-07-21T16:17:48.439Z",
+    "originalVersion": "7.6.0",
+    "processedAt": "2026-08-25T00:16:52.187Z",
     "smokeTest": "passed"
   }
 }

package/src/bulk/common.ts

@@ -157,6 +157,7 @@ export class Batch<T = Document> {
   originalIndexes: number[];
   batchType: BatchType;
   operations: T[];
+  serializedOperations: Uint8Array[];
   size: number;
   sizeBytes: number;
 
@@ -166,6 +167,7 @@ export class Batch<T = Document> {
     this.originalIndexes = [];
     this.batchType = batchType;
     this.operations = [];
+    this.serializedOperations = [];
     this.size = 0;
     this.sizeBytes = 0;
   }
@@ -538,12 +540,31 @@ async function executeCommands(
       }
     }
 
+    // The per-operation buffers were serialized in addToOperationsList using the
+    // bulk operation's BSON options. Reuse them only when the serialization
+    // options in effect for this execution still match, so that BSON options
+    // supplied to execute() (e.g. `ignoreUndefined`) are honored. Also skip reuse
+    // under auto-encryption, where libmongocrypt requires the plaintext command
+    // (document sequences are not permitted per the bulkWrite spec).
+    const createdBsonOptions = bulkOperation.s.bsonOptions;
+    const canReuseSerialized =
+      !bulkOperation.s.usingAutoEncryption &&
+      finalOptions.ignoreUndefined === createdBsonOptions.ignoreUndefined &&
+      finalOptions.serializeFunctions === createdBsonOptions.serializeFunctions &&
+      (finalOptions.checkKeys ?? false) === bulkOperation.s.checkKeys;
+    const serialized = canReuseSerialized ? batch.serializedOperations : undefined;
+
     const operation = isInsertBatch(batch)
-      ? new InsertOperation(bulkOperation.s.namespace, batch.operations, finalOptions)
+      ? new InsertOperation(bulkOperation.s.namespace, batch.operations, finalOptions, serialized)
       : isUpdateBatch(batch)
-        ? new UpdateOperation(bulkOperation.s.namespace, batch.operations, finalOptions)
+        ? new UpdateOperation(bulkOperation.s.namespace, batch.operations, finalOptions, serialized)
         : isDeleteBatch(batch)
-          ? new DeleteOperation(bulkOperation.s.namespace, batch.operations, finalOptions)
+          ? new DeleteOperation(
+              bulkOperation.s.namespace,
+              batch.operations,
+              finalOptions,
+              serialized
+            )
           : null;
 
     if (operation == null) throw new MongoRuntimeError(`Unknown batchType: ${batch.batchType}`);
@@ -560,6 +581,15 @@ async function executeCommands(
       thrownError = error;
     }
 
+    // Release this batch's serialized buffers now that it has been sent. The
+    // operation keeps its own reference to the array for the duration of its
+    // execution and any retries, so reassigning here (rather than mutating the
+    // shared array) only drops the bulk operation's copy. All batches are built
+    // up front, so this does not lower the peak (reached before the first send);
+    // it frees each batch's buffers as that batch completes so they are not kept
+    // alive through the remaining batches' round trips.
+    batch.serializedOperations = [];
+
     if (thrownError != null) {
       if (thrownError instanceof MongoWriteConcernError) {
         mergeBatchResults(batch, bulkOperation.s.bulkResult, thrownError, result);
@@ -824,6 +854,7 @@ export interface BulkOperationPrivate {
   // check keys
   checkKeys: boolean;
   bypassDocumentValidation?: boolean;
+  usingAutoEncryption: boolean;
 }
 
 /** @public */
@@ -953,7 +984,8 @@ export abstract class BulkOperationBase {
       // Fundamental error
       err: undefined,
       // check keys
-      checkKeys: typeof options.checkKeys === 'boolean' ? options.checkKeys : false
+      checkKeys: typeof options.checkKeys === 'boolean' ? options.checkKeys : false,
+      usingAutoEncryption
     };
 
     // bypass Validation
@@ -1011,7 +1043,7 @@ export abstract class BulkOperationBase {
    * // Add a replaceOne
    * bulkOp.find({ i: 9 }).replaceOne({writeConcern: { j: 10 }});
    *
-   * // Update using a pipeline (requires Mongodb 4.2 or higher)
+   * // Update using a pipeline
    * bulk.find({ k: 11, y: { $exists: true }, z: { $exists: true } }).updateOne([
    *   { $set: { total: { $sum: [ '$y', '$z' ] } } }
    * ]);

package/src/bulk/ordered.ts

@@ -17,13 +17,28 @@ export class OrderedBulkOperation extends BulkOperationBase {
     batchType: BatchType,
     document: Document | UpdateStatement | DeleteStatement
   ): this {
-    // Get the bsonSize
-    const bsonSize = BSON.calculateObjectSize(document, {
-      checkKeys: false,
-      // Since we don't know what the user selected for BSON options here,
-      // err on the safe side, and check the size with ignoreUndefined: false.
-      ignoreUndefined: false
-    } as any);
+    // Serialize the operation once here and reuse the bytes for both the size
+    // check/splitting and the wire message (via a DocumentSequence). Under
+    // auto-encryption the command is sent as a BSON array rather than a
+    // document sequence, so the buffer would never be reused; there we only
+    // measure the size and leave `buffer` undefined so nothing is retained on
+    // the batch.
+    let buffer: Uint8Array | undefined;
+    let bsonSize: number;
+    if (this.s.usingAutoEncryption) {
+      bsonSize = BSON.calculateObjectSize(document, {
+        checkKeys: false,
+        ignoreUndefined: false
+      } as any);
+    } else {
+      const bson = this.s.bsonOptions;
+      buffer = BSON.serialize(document, {
+        checkKeys: this.s.checkKeys,
+        ignoreUndefined: bson.ignoreUndefined,
+        serializeFunctions: bson.serializeFunctions
+      });
+      bsonSize = buffer.length;
+    }
 
     // Throw error if the doc is bigger than the max BSON size
     if (bsonSize >= this.s.maxBsonObjectSize)
@@ -75,6 +90,7 @@ export class OrderedBulkOperation extends BulkOperationBase {
 
     this.s.currentBatch.originalIndexes.push(this.s.currentIndex);
     this.s.currentBatch.operations.push(document);
+    if (buffer != null) this.s.currentBatch.serializedOperations.push(buffer);
     this.s.currentBatchSize += 1;
     this.s.currentBatchSizeBytes += maxKeySize + bsonSize;
     this.s.currentIndex += 1;

package/src/bulk/unordered.ts

@@ -31,14 +31,28 @@ export class UnorderedBulkOperation extends BulkOperationBase {
     batchType: BatchType,
     document: Document | UpdateStatement | DeleteStatement
   ): this {
-    // Get the bsonSize
-    const bsonSize = BSON.calculateObjectSize(document, {
-      checkKeys: false,
-
-      // Since we don't know what the user selected for BSON options here,
-      // err on the safe side, and check the size with ignoreUndefined: false.
-      ignoreUndefined: false
-    } as any);
+    // Serialize the operation once here and reuse the bytes for both the size
+    // check/splitting and the wire message (via a DocumentSequence). Under
+    // auto-encryption the command is sent as a BSON array rather than a
+    // document sequence, so the buffer would never be reused; there we only
+    // measure the size and leave `buffer` undefined so nothing is retained on
+    // the batch.
+    let buffer: Uint8Array | undefined;
+    let bsonSize: number;
+    if (this.s.usingAutoEncryption) {
+      bsonSize = BSON.calculateObjectSize(document, {
+        checkKeys: false,
+        ignoreUndefined: false
+      } as any);
+    } else {
+      const bson = this.s.bsonOptions;
+      buffer = BSON.serialize(document, {
+        checkKeys: this.s.checkKeys,
+        ignoreUndefined: bson.ignoreUndefined,
+        serializeFunctions: bson.serializeFunctions
+      });
+      bsonSize = buffer.length;
+    }
 
     // Throw error if the doc is bigger than the max BSON size
     if (bsonSize >= this.s.maxBsonObjectSize) {
@@ -90,6 +104,7 @@ export class UnorderedBulkOperation extends BulkOperationBase {
     }
 
     this.s.currentBatch.operations.push(document);
+    if (buffer != null) this.s.currentBatch.serializedOperations.push(buffer);
     this.s.currentBatch.originalIndexes.push(this.s.currentIndex);
     this.s.currentIndex = this.s.currentIndex + 1;
 

package/src/client-side-encryption/auto_encrypter.ts

@@ -11,6 +11,7 @@ import { type Abortable } from '../mongo_types';
 import { MongoDBCollectionNamespace } from '../utils';
 import { autoSelectSocketOptions } from './client_encryption';
 import { defaultErrorWrapper, MongoCryptInvalidArgumentError } from './errors';
+import { type CSFLEKMSTlsOptions, type KMSConnectCallback } from './kms_options';
 import { MongocryptdManager } from './mongocryptd_manager';
 import {
   type CredentialProviders,
@@ -18,7 +19,7 @@ import {
   type KMSProviders,
   refreshKMSCredentials
 } from './providers';
-import { type CSFLEKMSTlsOptions, StateMachine } from './state_machine';
+import { StateMachine } from './state_machine';
 
 /** @public */
 export interface AutoEncryptionOptions {
@@ -110,6 +111,12 @@ export interface AutoEncryptionOptions {
   proxyOptions?: ProxyOptions;
   /** The TLS options to use connecting to the KMS provider */
   tlsOptions?: CSFLEKMSTlsOptions;
+  /**
+   * A callback that establishes the socket used to connect to a KMS host, e.g. to route KMS
+   * requests through an HTTP proxy via the HTTP CONNECT method. Mutually exclusive with `proxyOptions`.
+   * See {@link KMSConnectCallback} for a usage example.
+   */
+  kmsConnectCallback?: KMSConnectCallback;
 }
 
 /**
@@ -156,6 +163,7 @@ export class AutoEncrypter {
   _metaDataClient: MongoClient;
   _proxyOptions: ProxyOptions;
   _tlsOptions: CSFLEKMSTlsOptions;
+  _kmsConnectCallback?: KMSConnectCallback;
   _kmsProviders: KMSProviders;
   _bypassMongocryptdAndCryptShared: boolean;
   _contextCounter: number;
@@ -242,7 +250,13 @@ export class AutoEncrypter {
     this._keyVaultClient = options.keyVaultClient || client;
     this._metaDataClient = options.metadataClient || client;
     this._proxyOptions = options.proxyOptions || {};
+    if (this._proxyOptions.proxyHost && options.kmsConnectCallback) {
+      throw new MongoCryptInvalidArgumentError(
+        'Cannot set both proxyOptions and kmsConnectCallback'
+      );
+    }
     this._tlsOptions = options.tlsOptions || {};
+    this._kmsConnectCallback = options.kmsConnectCallback;
     this._kmsProviders = options.kmsProviders || {};
     this._credentialProviders = options.credentialProviders;
 
@@ -417,7 +431,8 @@ export class AutoEncrypter {
       promoteLongs: false,
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
 
     return deserialize(await stateMachine.execute(this, context, options), {
@@ -443,7 +458,8 @@ export class AutoEncrypter {
       ...options,
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
 
     return await stateMachine.execute(this, context, options);

package/src/client-side-encryption/client_encryption.ts

@@ -31,6 +31,11 @@ import {
   MongoCryptCreateEncryptedCollectionError,
   MongoCryptInvalidArgumentError
 } from './errors';
+import {
+  type ClientEncryptionSocketOptions,
+  type CSFLEKMSTlsOptions,
+  type KMSConnectCallback
+} from './kms_options';
 import {
   type ClientEncryptionDataKeyProvider,
   type CredentialProviders,
@@ -38,11 +43,7 @@ import {
   type KMSProviders,
   refreshKMSCredentials
 } from './providers/index';
-import {
-  type ClientEncryptionSocketOptions,
-  type CSFLEKMSTlsOptions,
-  StateMachine
-} from './state_machine';
+import { StateMachine } from './state_machine';
 
 /**
  * @public
@@ -75,6 +76,8 @@ export class ClientEncryption {
   /** @internal */
   _tlsOptions: CSFLEKMSTlsOptions;
   /** @internal */
+  _kmsConnectCallback?: KMSConnectCallback;
+  /** @internal */
   _kmsProviders: KMSProviders;
   /** @internal */
   _timeoutMS?: number;
@@ -125,7 +128,13 @@ export class ClientEncryption {
   constructor(client: MongoClient, options: ClientEncryptionOptions) {
     this._client = client;
     this._proxyOptions = options.proxyOptions ?? {};
+    if (this._proxyOptions.proxyHost && options.kmsConnectCallback) {
+      throw new MongoCryptInvalidArgumentError(
+        'Cannot set both proxyOptions and kmsConnectCallback'
+      );
+    }
     this._tlsOptions = options.tlsOptions ?? {};
+    this._kmsConnectCallback = options.kmsConnectCallback;
     this._kmsProviders = options.kmsProviders || {};
     const { timeoutMS } = resolveTimeoutOptions(client, options);
     this._timeoutMS = timeoutMS;
@@ -226,7 +235,8 @@ export class ClientEncryption {
     const stateMachine = new StateMachine({
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
 
     const timeoutContext =
@@ -295,7 +305,8 @@ export class ClientEncryption {
     const stateMachine = new StateMachine({
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
 
     const timeoutContext = TimeoutContext.create(
@@ -699,7 +710,8 @@ export class ClientEncryption {
     const stateMachine = new StateMachine({
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
 
     const timeoutContext =
@@ -797,7 +809,8 @@ export class ClientEncryption {
     const stateMachine = new StateMachine({
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions,
-      socketOptions: autoSelectSocketOptions(this._client.s.options)
+      socketOptions: autoSelectSocketOptions(this._client.s.options),
+      kmsConnectCallback: this._kmsConnectCallback
     });
     const context = this._mongoCrypt.makeExplicitEncryptionContext(valueBuffer, contextOptions);
 
@@ -961,6 +974,13 @@ export interface ClientEncryptionOptions {
    */
   tlsOptions?: CSFLEKMSTlsOptions;
 
+  /**
+   * A callback that establishes the socket used to connect to a KMS host, e.g. to route KMS
+   * requests through an HTTP proxy via the HTTP CONNECT method. Mutually exclusive with `proxyOptions`.
+   * See {@link KMSConnectCallback} for a usage example.
+   */
+  kmsConnectCallback?: KMSConnectCallback;
+
   /**
    * Sets the expiration time for the DEK in the cache in milliseconds. Defaults to 60000. 0 means no timeout.
    */