mongodb 6.7.0 → 6.8.0-dev.20240629.sha.d85f827a

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

@@ -6,6 +6,7 @@ import {
 
 import { deserialize, type Document, serialize } from '../bson';
 import { type CommandOptions, type ProxyOptions } from '../cmap/connection';
+import { kDecorateResult } from '../constants';
 import { getMongoDBClientEncryption } from '../deps';
 import { MongoRuntimeError } from '../error';
 import { MongoClient, type MongoClientOptions } from '../mongo_client';
@@ -25,85 +26,7 @@ export interface AutoEncryptionOptions {
   /** The namespace where keys are stored in the key vault */
   keyVaultNamespace?: string;
   /** Configuration options that are used by specific KMS providers during key generation, encryption, and decryption. */
-  kmsProviders?: {
-    /** Configuration options for using 'aws' as your KMS provider */
-    aws?:
-      | {
-          /** The access key used for the AWS KMS provider */
-          accessKeyId: string;
-          /** The secret access key used for the AWS KMS provider */
-          secretAccessKey: string;
-          /**
-           * An optional AWS session token that will be used as the
-           * X-Amz-Security-Token header for AWS requests.
-           */
-          sessionToken?: string;
-        }
-      | Record<string, never>;
-    /** Configuration options for using 'local' as your KMS provider */
-    local?: {
-      /**
-       * The master key used to encrypt/decrypt data keys.
-       * A 96-byte long Buffer or base64 encoded string.
-       */
-      key: Buffer | string;
-    };
-    /** Configuration options for using 'azure' as your KMS provider */
-    azure?:
-      | {
-          /** The tenant ID identifies the organization for the account */
-          tenantId: string;
-          /** The client ID to authenticate a registered application */
-          clientId: string;
-          /** The client secret to authenticate a registered application */
-          clientSecret: string;
-          /**
-           * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-           * This is optional, and only needed if customer is using a non-commercial Azure instance
-           * (e.g. a government or China account, which use different URLs).
-           * Defaults to "login.microsoftonline.com"
-           */
-          identityPlatformEndpoint?: string | undefined;
-        }
-      | {
-          /**
-           * If present, an access token to authenticate with Azure.
-           */
-          accessToken: string;
-        }
-      | Record<string, never>;
-    /** Configuration options for using 'gcp' as your KMS provider */
-    gcp?:
-      | {
-          /** The service account email to authenticate */
-          email: string;
-          /** A PKCS#8 encrypted key. This can either be a base64 string or a binary representation */
-          privateKey: string | Buffer;
-          /**
-           * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-           * Defaults to "oauth2.googleapis.com"
-           */
-          endpoint?: string | undefined;
-        }
-      | {
-          /**
-           * If present, an access token to authenticate with GCP.
-           */
-          accessToken: string;
-        }
-      | Record<string, never>;
-    /**
-     * Configuration options for using 'kmip' as your KMS provider
-     */
-    kmip?: {
-      /**
-       * The output endpoint string.
-       * The endpoint consists of a hostname and port separated by a colon.
-       * E.g. "example.com:123". A port is always present.
-       */
-      endpoint?: string;
-    };
-  };
+  kmsProviders?: KMSProviders;
   /**
    * A map of namespaces to a local JSON schema for encryption
    *
@@ -212,15 +135,6 @@ export const AutoEncryptionLoggerLevel = Object.freeze({
 export type AutoEncryptionLoggerLevel =
   (typeof AutoEncryptionLoggerLevel)[keyof typeof AutoEncryptionLoggerLevel];
 
-// Typescript errors if we index objects with `Symbol.for(...)`, so
-// to avoid TS errors we pull them out into variables.  Then we can type
-// the objects (and class) that we expect to see them on and prevent TS
-// errors.
-/** @internal */
-const kDecorateResult = Symbol.for('@@mdb.decorateDecryptionResult');
-/** @internal */
-const kDecoratedKeys = Symbol.for('@@mdb.decryptedKeys');
-
 /**
  * @internal An internal class to be used by the driver for auto encryption
  * **NOTE**: Not meant to be instantiated directly, this is for internal use only.
@@ -467,16 +381,18 @@ export class AutoEncrypter {
       proxyOptions: this._proxyOptions,
       tlsOptions: this._tlsOptions
     });
-    return await stateMachine.execute<Document>(this, context);
+
+    return deserialize(await stateMachine.execute(this, context), {
+      promoteValues: false,
+      promoteLongs: false
+    });
   }
 
   /**
    * Decrypt a command response
    */
-  async decrypt(response: Uint8Array | Document, options: CommandOptions = {}): Promise<Document> {
-    const buffer = Buffer.isBuffer(response) ? response : serialize(response, options);
-
-    const context = this._mongocrypt.makeDecryptionContext(buffer);
+  async decrypt(response: Uint8Array, options: CommandOptions = {}): Promise<Uint8Array> {
+    const context = this._mongocrypt.makeDecryptionContext(response);
 
     context.id = this._contextCounter++;
 
@@ -486,12 +402,7 @@ export class AutoEncrypter {
       tlsOptions: this._tlsOptions
     });
 
-    const decorateResult = this[kDecorateResult];
-    const result = await stateMachine.execute<Document>(this, context);
-    if (decorateResult) {
-      decorateDecryptionResult(result, response);
-    }
-    return result;
+    return await stateMachine.execute(this, context);
   }
 
   /**
@@ -518,53 +429,3 @@ export class AutoEncrypter {
     return AutoEncrypter.getMongoCrypt().libmongocryptVersion;
   }
 }
-
-/**
- * Recurse through the (identically-shaped) `decrypted` and `original`
- * objects and attach a `decryptedKeys` property on each sub-object that
- * contained encrypted fields. Because we only call this on BSON responses,
- * we do not need to worry about circular references.
- *
- * @internal
- */
-function decorateDecryptionResult(
-  decrypted: Document & { [kDecoratedKeys]?: Array<string> },
-  original: Document,
-  isTopLevelDecorateCall = true
-): void {
-  if (isTopLevelDecorateCall) {
-    // The original value could have been either a JS object or a BSON buffer
-    if (Buffer.isBuffer(original)) {
-      original = deserialize(original);
-    }
-    if (Buffer.isBuffer(decrypted)) {
-      throw new MongoRuntimeError('Expected result of decryption to be deserialized BSON object');
-    }
-  }
-
-  if (!decrypted || typeof decrypted !== 'object') return;
-  for (const k of Object.keys(decrypted)) {
-    const originalValue = original[k];
-
-    // An object was decrypted by libmongocrypt if and only if it was
-    // a BSON Binary object with subtype 6.
-    if (originalValue && originalValue._bsontype === 'Binary' && originalValue.sub_type === 6) {
-      if (!decrypted[kDecoratedKeys]) {
-        Object.defineProperty(decrypted, kDecoratedKeys, {
-          value: [],
-          configurable: true,
-          enumerable: false,
-          writable: false
-        });
-      }
-      // this is defined in the preceding if-statement
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      decrypted[kDecoratedKeys]!.push(k);
-      // Do not recurse into this decrypted value. It could be a sub-document/array,
-      // in which case there is no original value associated with its subfields.
-      continue;
-    }
-
-    decorateDecryptionResult(decrypted[k], originalValue, false);
-  }
-}

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

@@ -5,7 +5,7 @@ import type {
   MongoCryptOptions
 } from 'mongodb-client-encryption';
 
-import { type Binary, type Document, type Long, serialize, type UUID } from '../bson';
+import { type Binary, deserialize, type Document, type Long, serialize, type UUID } from '../bson';
 import { type AnyBulkWriteOperation, type BulkWriteResult } from '../bulk/common';
 import { type ProxyOptions } from '../cmap/connection';
 import { type Collection } from '../collection';
@@ -202,7 +202,7 @@ export class ClientEncryption {
       tlsOptions: this._tlsOptions
     });
 
-    const dataKey = await stateMachine.execute<DataKey>(this, context);
+    const dataKey = deserialize(await stateMachine.execute(this, context)) as DataKey;
 
     const { db: dbName, collection: collectionName } = MongoDBCollectionNamespace.fromString(
       this._keyVaultNamespace
@@ -259,7 +259,7 @@ export class ClientEncryption {
       tlsOptions: this._tlsOptions
     });
 
-    const { v: dataKeys } = await stateMachine.execute<{ v: DataKey[] }>(this, context);
+    const { v: dataKeys } = deserialize(await stateMachine.execute(this, context));
     if (dataKeys.length === 0) {
       return {};
     }
@@ -640,7 +640,7 @@ export class ClientEncryption {
       tlsOptions: this._tlsOptions
     });
 
-    const { v } = await stateMachine.execute<{ v: T }>(this, context);
+    const { v } = deserialize(await stateMachine.execute(this, context));
 
     return v;
   }
@@ -719,8 +719,8 @@ export class ClientEncryption {
     });
     const context = this._mongoCrypt.makeExplicitEncryptionContext(valueBuffer, contextOptions);
 
-    const result = await stateMachine.execute<{ v: Binary }>(this, context);
-    return result.v;
+    const { v } = deserialize(await stateMachine.execute(this, context));
+    return v;
   }
 }
 
@@ -773,6 +773,7 @@ export interface ClientEncryptionRewrapManyDataKeyProviderOptions {
     | AWSEncryptionKeyOptions
     | AzureEncryptionKeyOptions
     | GCPEncryptionKeyOptions
+    | KMIPEncryptionKeyOptions
     | undefined;
 }
 
@@ -885,6 +886,31 @@ export interface AzureEncryptionKeyOptions {
   keyVersion?: string | undefined;
 }
 
+/**
+ * @public
+ * Configuration options for making a KMIP encryption key
+ */
+export interface KMIPEncryptionKeyOptions {
+  /**
+   * keyId is the KMIP Unique Identifier to a 96 byte KMIP Secret Data managed object.
+   *
+   * If keyId is omitted, a random 96 byte KMIP Secret Data managed object will be created.
+   */
+  keyId?: string;
+
+  /**
+   * Host with optional port.
+   */
+  endpoint?: string;
+
+  /**
+   * If true, this key should be decrypted by the KMIP server.
+   *
+   * Requires `mongodb-client-encryption>=6.0.1`.
+   */
+  delegated?: boolean;
+}
+
 /**
  * @public
  * Options to provide when creating a new data key.
@@ -897,6 +923,7 @@ export interface ClientEncryptionCreateDataKeyProviderOptions {
     | AWSEncryptionKeyOptions
     | AzureEncryptionKeyOptions
     | GCPEncryptionKeyOptions
+    | KMIPEncryptionKeyOptions
     | undefined;
 
   /**
@@ -909,19 +936,6 @@ export interface ClientEncryptionCreateDataKeyProviderOptions {
   keyMaterial?: Buffer | Binary;
 }
 
-/**
- * @public
- * @experimental
- */
-export interface ClientEncryptionRewrapManyDataKeyProviderOptions {
-  provider: ClientEncryptionDataKeyProvider;
-  masterKey?:
-    | AWSEncryptionKeyOptions
-    | AzureEncryptionKeyOptions
-    | GCPEncryptionKeyOptions
-    | undefined;
-}
-
 /**
  * @public
  * @experimental

package/src/client-side-encryption/providers/index.ts

@@ -1,127 +1,153 @@
+import type { Binary } from '../../bson';
 import { loadAWSCredentials } from './aws';
 import { loadAzureCredentials } from './azure';
 import { loadGCPCredentials } from './gcp';
 
 /**
  * @public
+ *
+ * A data key provider.  Allowed values:
+ *
+ * - aws, gcp, local, kmip or azure
+ * - (`mongodb-client-encryption>=6.0.1` only) a named key, in the form of:
+ *    `aws:<name>`, `gcp:<name>`, `local:<name>`, `kmip:<name>`, `azure:<name>`
+ *  where `name` is an alphanumeric string, underscores allowed.
  */
-export type ClientEncryptionDataKeyProvider = 'aws' | 'azure' | 'gcp' | 'local' | 'kmip';
+export type ClientEncryptionDataKeyProvider = keyof KMSProviders;
+
+/** @public */
+export interface AWSKMSProviderConfiguration {
+  /**
+   * The access key used for the AWS KMS provider
+   */
+  accessKeyId: string;
+
+  /**
+   * The secret access key used for the AWS KMS provider
+   */
+  secretAccessKey: string;
+
+  /**
+   * An optional AWS session token that will be used as the
+   * X-Amz-Security-Token header for AWS requests.
+   */
+  sessionToken?: string;
+}
+
+/** @public */
+export interface LocalKMSProviderConfiguration {
+  /**
+   * The master key used to encrypt/decrypt data keys.
+   * A 96-byte long Buffer or base64 encoded string.
+   */
+  key: Binary | Uint8Array | string;
+}
+
+/** @public */
+export interface KMIPKMSProviderConfiguration {
+  /**
+   * The output endpoint string.
+   * The endpoint consists of a hostname and port separated by a colon.
+   * E.g. "example.com:123". A port is always present.
+   */
+  endpoint?: string;
+}
+
+/** @public */
+export type AzureKMSProviderConfiguration =
+  | {
+      /**
+       * The tenant ID identifies the organization for the account
+       */
+      tenantId: string;
+
+      /**
+       * The client ID to authenticate a registered application
+       */
+      clientId: string;
+
+      /**
+       * The client secret to authenticate a registered application
+       */
+      clientSecret: string;
+
+      /**
+       * If present, a host with optional port. E.g. "example.com" or "example.com:443".
+       * This is optional, and only needed if customer is using a non-commercial Azure instance
+       * (e.g. a government or China account, which use different URLs).
+       * Defaults to "login.microsoftonline.com"
+       */
+      identityPlatformEndpoint?: string | undefined;
+    }
+  | {
+      /**
+       * If present, an access token to authenticate with Azure.
+       */
+      accessToken: string;
+    };
+
+/** @public */
+export type GCPKMSProviderConfiguration =
+  | {
+      /**
+       * The service account email to authenticate
+       */
+      email: string;
+
+      /**
+       * A PKCS#8 encrypted key. This can either be a base64 string or a binary representation
+       */
+      privateKey: string | Buffer;
+
+      /**
+       * If present, a host with optional port. E.g. "example.com" or "example.com:443".
+       * Defaults to "oauth2.googleapis.com"
+       */
+      endpoint?: string | undefined;
+    }
+  | {
+      /**
+       * If present, an access token to authenticate with GCP.
+       */
+      accessToken: string;
+    };
 
 /**
  * @public
  * Configuration options that are used by specific KMS providers during key generation, encryption, and decryption.
+ *
+ * Named KMS providers _are not supported_ for automatic KMS credential fetching.
  */
 export interface KMSProviders {
   /**
    * Configuration options for using 'aws' as your KMS provider
    */
-  aws?:
-    | {
-        /**
-         * The access key used for the AWS KMS provider
-         */
-        accessKeyId: string;
-
-        /**
-         * The secret access key used for the AWS KMS provider
-         */
-        secretAccessKey: string;
-
-        /**
-         * An optional AWS session token that will be used as the
-         * X-Amz-Security-Token header for AWS requests.
-         */
-        sessionToken?: string;
-      }
-    | Record<string, never>;
+  aws?: AWSKMSProviderConfiguration | Record<string, never>;
+  [key: `aws:${string}`]: AWSKMSProviderConfiguration;
 
   /**
    * Configuration options for using 'local' as your KMS provider
    */
-  local?: {
-    /**
-     * The master key used to encrypt/decrypt data keys.
-     * A 96-byte long Buffer or base64 encoded string.
-     */
-    key: Buffer | string;
-  };
+  local?: LocalKMSProviderConfiguration;
+  [key: `local:${string}`]: LocalKMSProviderConfiguration;
 
   /**
    * Configuration options for using 'kmip' as your KMS provider
    */
-  kmip?: {
-    /**
-     * The output endpoint string.
-     * The endpoint consists of a hostname and port separated by a colon.
-     * E.g. "example.com:123". A port is always present.
-     */
-    endpoint?: string;
-  };
+  kmip?: KMIPKMSProviderConfiguration;
+  [key: `kmip:${string}`]: KMIPKMSProviderConfiguration;
 
   /**
    * Configuration options for using 'azure' as your KMS provider
    */
-  azure?:
-    | {
-        /**
-         * The tenant ID identifies the organization for the account
-         */
-        tenantId: string;
-
-        /**
-         * The client ID to authenticate a registered application
-         */
-        clientId: string;
-
-        /**
-         * The client secret to authenticate a registered application
-         */
-        clientSecret: string;
-
-        /**
-         * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-         * This is optional, and only needed if customer is using a non-commercial Azure instance
-         * (e.g. a government or China account, which use different URLs).
-         * Defaults to "login.microsoftonline.com"
-         */
-        identityPlatformEndpoint?: string | undefined;
-      }
-    | {
-        /**
-         * If present, an access token to authenticate with Azure.
-         */
-        accessToken: string;
-      }
-    | Record<string, never>;
+  azure?: AzureKMSProviderConfiguration | Record<string, never>;
+  [key: `azure:${string}`]: AzureKMSProviderConfiguration;
 
   /**
    * Configuration options for using 'gcp' as your KMS provider
    */
-  gcp?:
-    | {
-        /**
-         * The service account email to authenticate
-         */
-        email: string;
-
-        /**
-         * A PKCS#8 encrypted key. This can either be a base64 string or a binary representation
-         */
-        privateKey: string | Buffer;
-
-        /**
-         * If present, a host with optional port. E.g. "example.com" or "example.com:443".
-         * Defaults to "oauth2.googleapis.com"
-         */
-        endpoint?: string | undefined;
-      }
-    | {
-        /**
-         * If present, an access token to authenticate with GCP.
-         */
-        accessToken: string;
-      }
-    | Record<string, never>;
+  gcp?: GCPKMSProviderConfiguration | Record<string, never>;
+  [key: `gcp:${string}`]: GCPKMSProviderConfiguration;
 }
 
 /**

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

@@ -17,7 +17,7 @@ import { BufferPool, MongoDBCollectionNamespace, promiseWithResolvers } from '..
 import { type DataKey } from './client_encryption';
 import { MongoCryptError } from './errors';
 import { type MongocryptdManager } from './mongocryptd_manager';
-import { type ClientEncryptionDataKeyProvider, type KMSProviders } from './providers';
+import { type KMSProviders } from './providers';
 
 let socks: SocksLib | null = null;
 function loadSocks(): SocksLib {
@@ -110,8 +110,23 @@ export type CSFLEKMSTlsOptions = {
   kmip?: ClientEncryptionTlsOptions;
   local?: ClientEncryptionTlsOptions;
   azure?: ClientEncryptionTlsOptions;
+
+  [key: string]: ClientEncryptionTlsOptions | undefined;
 };
 
+/**
+ * This is kind of a hack.  For `rewrapManyDataKey`, we have tests that
+ * guarantee that when there are no matching keys, `rewrapManyDataKey` returns
+ * nothing.  We also have tests for auto encryption that guarantee for `encrypt`
+ * we return an error when there are no matching keys.  This error is generated in
+ * subsequent iterations of the state machine.
+ * Some apis (`encrypt`) throw if there are no filter matches and others (`rewrapManyDataKey`)
+ * do not.  We set the result manually here, and let the state machine continue.  `libmongocrypt`
+ * will inform us if we need to error by setting the state to `MONGOCRYPT_CTX_ERROR` but
+ * otherwise we'll return `{ v: [] }`.
+ */
+let EMPTY_V;
+
 /**
  * @internal
  *
@@ -154,16 +169,13 @@ export class StateMachine {
   /**
    * Executes the state machine according to the specification
    */
-  async execute<T extends Document>(
-    executor: StateMachineExecutable,
-    context: MongoCryptContext
-  ): Promise<T> {
+  async execute(executor: StateMachineExecutable, context: MongoCryptContext): Promise<Uint8Array> {
     const keyVaultNamespace = executor._keyVaultNamespace;
     const keyVaultClient = executor._keyVaultClient;
     const metaDataClient = executor._metaDataClient;
     const mongocryptdClient = executor._mongocryptdClient;
     const mongocryptdManager = executor._mongocryptdManager;
-    let result: T | null = null;
+    let result: Uint8Array | null = null;
 
     while (context.state !== MONGOCRYPT_CTX_DONE && context.state !== MONGOCRYPT_CTX_ERROR) {
       debug(`[context#${context.id}] ${stateToString.get(context.state) || context.state}`);
@@ -211,16 +223,8 @@ export class StateMachine {
           const keys = await this.fetchKeys(keyVaultClient, keyVaultNamespace, filter);
 
           if (keys.length === 0) {
-            // This is kind of a hack.  For `rewrapManyDataKey`, we have tests that
-            // guarantee that when there are no matching keys, `rewrapManyDataKey` returns
-            // nothing.  We also have tests for auto encryption that guarantee for `encrypt`
-            // we return an error when there are no matching keys.  This error is generated in
-            // subsequent iterations of the state machine.
-            // Some apis (`encrypt`) throw if there are no filter matches and others (`rewrapManyDataKey`)
-            // do not.  We set the result manually here, and let the state machine continue.  `libmongocrypt`
-            // will inform us if we need to error by setting the state to `MONGOCRYPT_CTX_ERROR` but
-            // otherwise we'll return `{ v: [] }`.
-            result = { v: [] } as any as T;
+            // See docs on EMPTY_V
+            result = EMPTY_V ??= serialize({ v: [] });
           }
           for await (const key of keys) {
             context.addMongoOperationResponse(serialize(key));
@@ -252,7 +256,7 @@ export class StateMachine {
             const message = context.status.message || 'Finalization error';
             throw new MongoCryptError(message);
           }
-          result = deserialize(finalizedContext, this.options) as T;
+          result = finalizedContext;
           break;
         }
 
@@ -319,7 +323,7 @@ export class StateMachine {
 
     const tlsOptions = this.options.tlsOptions;
     if (tlsOptions) {
-      const kmsProvider = request.kmsProvider as ClientEncryptionDataKeyProvider;
+      const kmsProvider = request.kmsProvider;
       const providerTlsOptions = tlsOptions[kmsProvider];
       if (providerTlsOptions) {
         const error = this.validateTlsOptions(kmsProvider, providerTlsOptions);