@depup/mongodb 7.1.0-depup.0

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

@@ -0,0 +1,144 @@
+import { type Document } from '../bson';
+import { MongoError } from '../error';
+
+/**
+ * @public
+ * An error indicating that something went wrong specifically with MongoDB Client Encryption
+ */
+export class MongoCryptError extends MongoError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(message: string, options: { cause?: Error } = {}) {
+    super(message, options);
+  }
+
+  override get name() {
+    return 'MongoCryptError';
+  }
+}
+
+export const defaultErrorWrapper = (error: Error) =>
+  new MongoCryptError(error.message, { cause: error });
+
+/**
+ * @public
+ *
+ * An error indicating an invalid argument was provided to an encryption API.
+ */
+export class MongoCryptInvalidArgumentError extends MongoCryptError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(message: string) {
+    super(message);
+  }
+
+  override get name() {
+    return 'MongoCryptInvalidArgumentError';
+  }
+}
+/**
+ * @public
+ * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create data keys
+ */
+export class MongoCryptCreateDataKeyError extends MongoCryptError {
+  encryptedFields: Document;
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(encryptedFields: Document, { cause }: { cause: Error }) {
+    super(`Unable to complete creating data keys: ${cause.message}`, { cause });
+    this.encryptedFields = encryptedFields;
+  }
+
+  override get name() {
+    return 'MongoCryptCreateDataKeyError';
+  }
+}
+
+/**
+ * @public
+ * An error indicating that `ClientEncryption.createEncryptedCollection()` failed to create a collection
+ */
+export class MongoCryptCreateEncryptedCollectionError extends MongoCryptError {
+  encryptedFields: Document;
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(encryptedFields: Document, { cause }: { cause: Error }) {
+    super(`Unable to create collection: ${cause.message}`, { cause });
+    this.encryptedFields = encryptedFields;
+  }
+
+  override get name() {
+    return 'MongoCryptCreateEncryptedCollectionError';
+  }
+}
+
+/**
+ * @public
+ * An error indicating that mongodb-client-encryption failed to auto-refresh Azure KMS credentials.
+ */
+export class MongoCryptAzureKMSRequestError extends MongoCryptError {
+  /** The body of the http response that failed, if present. */
+  body?: Document;
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(message: string, body?: Document) {
+    super(message);
+    this.body = body;
+  }
+
+  override get name(): string {
+    return 'MongoCryptAzureKMSRequestError';
+  }
+}
+
+/** @public */
+export class MongoCryptKMSRequestNetworkTimeoutError extends MongoCryptError {
+  override get name(): string {
+    return 'MongoCryptKMSRequestNetworkTimeoutError';
+  }
+}

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

@@ -0,0 +1,100 @@
+import type { ChildProcess } from 'child_process';
+
+import { MongoNetworkTimeoutError } from '../error';
+import { type AutoEncryptionExtraOptions } from './auto_encrypter';
+
+/**
+ * @internal
+ * An internal class that handles spawning a mongocryptd.
+ */
+export class MongocryptdManager {
+  static DEFAULT_MONGOCRYPTD_URI = 'mongodb://localhost:27020';
+
+  uri: string;
+  bypassSpawn: boolean;
+  spawnPath = '';
+  spawnArgs: Array<string> = [];
+  _child?: ChildProcess;
+
+  constructor(extraOptions: AutoEncryptionExtraOptions = {}) {
+    this.uri =
+      typeof extraOptions.mongocryptdURI === 'string' && extraOptions.mongocryptdURI.length > 0
+        ? extraOptions.mongocryptdURI
+        : MongocryptdManager.DEFAULT_MONGOCRYPTD_URI;
+
+    this.bypassSpawn = !!extraOptions.mongocryptdBypassSpawn;
+
+    if (Object.hasOwn(extraOptions, 'mongocryptdSpawnPath') && extraOptions.mongocryptdSpawnPath) {
+      this.spawnPath = extraOptions.mongocryptdSpawnPath;
+    }
+    if (
+      Object.hasOwn(extraOptions, 'mongocryptdSpawnArgs') &&
+      Array.isArray(extraOptions.mongocryptdSpawnArgs)
+    ) {
+      this.spawnArgs = this.spawnArgs.concat(extraOptions.mongocryptdSpawnArgs);
+    }
+    if (
+      this.spawnArgs
+        .filter(arg => typeof arg === 'string')
+        .every(arg => arg.indexOf('--idleShutdownTimeoutSecs') < 0)
+    ) {
+      this.spawnArgs.push('--idleShutdownTimeoutSecs', '60');
+    }
+  }
+
+  /**
+   * Will check to see if a mongocryptd is up. If it is not up, it will attempt
+   * to spawn a mongocryptd in a detached process, and then wait for it to be up.
+   */
+  async spawn(): Promise<void> {
+    const cmdName = this.spawnPath || 'mongocryptd';
+
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { spawn } = require('child_process') as typeof import('child_process');
+
+    // Spawned with stdio: ignore and detached: true
+    // to ensure child can outlive parent.
+    this._child = spawn(cmdName, this.spawnArgs, {
+      stdio: 'ignore',
+      detached: true
+    });
+
+    this._child.on('error', () => {
+      // From the FLE spec:
+      // "The stdout and stderr of the spawned process MUST not be exposed in the driver
+      // (e.g. redirect to /dev/null). Users can pass the argument --logpath to
+      // extraOptions.mongocryptdSpawnArgs if they need to inspect mongocryptd logs.
+      // If spawning is necessary, the driver MUST spawn mongocryptd whenever server
+      // selection on the MongoClient to mongocryptd fails. If the MongoClient fails to
+      // connect after spawning, the server selection error is propagated to the user."
+      // The AutoEncrypter and MongoCryptdManager should work together to spawn
+      // mongocryptd whenever necessary.  Additionally, the `mongocryptd` intentionally
+      // shuts down after 60s and gets respawned when necessary.  We rely on server
+      // selection timeouts when connecting to the `mongocryptd` to inform users that something
+      // has been configured incorrectly.  For those reasons, we suppress stderr from
+      // the `mongocryptd` process and immediately unref the process.
+    });
+
+    // unref child to remove handle from event loop
+    this._child.unref();
+  }
+
+  /**
+   * @returns the result of `fn` or rejects with an error.
+   */
+  async withRespawn<T>(fn: () => Promise<T>): ReturnType<typeof fn> {
+    try {
+      const result = await fn();
+      return result;
+    } catch (err) {
+      // If we are not bypassing spawning, then we should retry once on a MongoTimeoutError (server selection error)
+      const shouldSpawn = err instanceof MongoNetworkTimeoutError && !this.bypassSpawn;
+      if (!shouldSpawn) {
+        throw err;
+      }
+    }
+    await this.spawn();
+    const result = await fn();
+    return result;
+  }
+}

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

@@ -0,0 +1,33 @@
+import {
+  type AWSCredentialProvider,
+  AWSSDKCredentialProvider
+} from '../../cmap/auth/aws_temporary_credentials';
+import { type KMSProviders } from '.';
+
+/**
+ * @internal
+ */
+export async function loadAWSCredentials(
+  kmsProviders: KMSProviders,
+  provider?: AWSCredentialProvider
+): Promise<KMSProviders> {
+  const credentialProvider = new AWSSDKCredentialProvider(provider);
+
+  // We shouldn't ever receive a response from the AWS SDK that doesn't have a `SecretAccessKey`
+  // or `AccessKeyId`.  However, TS says these fields are optional.  We provide empty strings
+  // and let libmongocrypt error if we're unable to fetch the required keys.
+  const {
+    SecretAccessKey = '',
+    AccessKeyId = '',
+    Token
+  } = await credentialProvider.getCredentials();
+  const aws: NonNullable<KMSProviders['aws']> = {
+    secretAccessKey: SecretAccessKey,
+    accessKeyId: AccessKeyId
+  };
+  // the AWS session token is only required for temporary credentials so only attach it to the
+  // result if it's present in the response from the aws sdk
+  Token != null && (aws.sessionToken = Token);
+
+  return { ...kmsProviders, aws };
+}

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

@@ -0,0 +1,181 @@
+import { type Document } from '../../bson';
+import { MongoNetworkTimeoutError } from '../../error';
+import { get } from '../../utils';
+import { MongoCryptAzureKMSRequestError } from '../errors';
+import { type KMSProviders } from './index';
+
+const MINIMUM_TOKEN_REFRESH_IN_MILLISECONDS = 6000;
+/** Base URL for getting Azure tokens. */
+export const AZURE_BASE_URL = 'http://169.254.169.254/metadata/identity/oauth2/token?';
+
+/**
+ * The access token that libmongocrypt expects for Azure kms.
+ */
+interface AccessToken {
+  accessToken: string;
+}
+
+/**
+ * The response from the azure idms endpoint, including the `expiresOnTimestamp`.
+ * `expiresOnTimestamp` is needed for caching.
+ */
+interface AzureTokenCacheEntry extends AccessToken {
+  accessToken: string;
+  expiresOnTimestamp: number;
+}
+
+/**
+ * @internal
+ */
+export class AzureCredentialCache {
+  cachedToken: AzureTokenCacheEntry | null = null;
+
+  async getToken(): Promise<AccessToken> {
+    if (this.cachedToken == null || this.needsRefresh(this.cachedToken)) {
+      this.cachedToken = await this._getToken();
+    }
+
+    return { accessToken: this.cachedToken.accessToken };
+  }
+
+  needsRefresh(token: AzureTokenCacheEntry): boolean {
+    const timeUntilExpirationMS = token.expiresOnTimestamp - Date.now();
+    return timeUntilExpirationMS <= MINIMUM_TOKEN_REFRESH_IN_MILLISECONDS;
+  }
+
+  /**
+   * exposed for testing
+   */
+  resetCache() {
+    this.cachedToken = null;
+  }
+
+  /**
+   * exposed for testing
+   */
+  _getToken(): Promise<AzureTokenCacheEntry> {
+    return fetchAzureKMSToken();
+  }
+}
+
+/** @internal */
+export const tokenCache = new AzureCredentialCache();
+
+/** @internal */
+async function parseResponse(response: {
+  body: string;
+  status?: number;
+}): Promise<AzureTokenCacheEntry> {
+  const { status, body: rawBody } = response;
+
+  const body: { expires_in?: number; access_token?: string } = (() => {
+    try {
+      return JSON.parse(rawBody);
+    } catch {
+      throw new MongoCryptAzureKMSRequestError('Malformed JSON body in GET request.');
+    }
+  })();
+
+  if (status !== 200) {
+    throw new MongoCryptAzureKMSRequestError('Unable to complete request.', body);
+  }
+
+  if (!body.access_token) {
+    throw new MongoCryptAzureKMSRequestError(
+      'Malformed response body - missing field `access_token`.'
+    );
+  }
+
+  if (!body.expires_in) {
+    throw new MongoCryptAzureKMSRequestError(
+      'Malformed response body - missing field `expires_in`.'
+    );
+  }
+
+  const expiresInMS = Number(body.expires_in) * 1000;
+  if (Number.isNaN(expiresInMS)) {
+    throw new MongoCryptAzureKMSRequestError(
+      'Malformed response body - unable to parse int from `expires_in` field.'
+    );
+  }
+
+  return {
+    accessToken: body.access_token,
+    expiresOnTimestamp: Date.now() + expiresInMS
+  };
+}
+
+/**
+ * @internal
+ *
+ * exposed for CSFLE
+ * [prose test 18](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/tests#azure-imds-credentials)
+ */
+export interface AzureKMSRequestOptions {
+  headers?: Document;
+  url?: URL | string;
+}
+
+/**
+ * @internal
+ * Get the Azure endpoint URL.
+ */
+export function addAzureParams(url: URL, resource: string, username?: string): URL {
+  url.searchParams.append('api-version', '2018-02-01');
+  url.searchParams.append('resource', resource);
+  if (username) {
+    url.searchParams.append('client_id', username);
+  }
+  return url;
+}
+
+/**
+ * @internal
+ *
+ * parses any options provided by prose tests to `fetchAzureKMSToken` and merges them with
+ * the default values for headers and the request url.
+ */
+export function prepareRequest(options: AzureKMSRequestOptions): {
+  headers: Document;
+  url: URL;
+} {
+  const url = new URL(options.url?.toString() ?? AZURE_BASE_URL);
+  addAzureParams(url, 'https://vault.azure.net');
+  const headers = { ...options.headers, 'Content-Type': 'application/json', Metadata: true };
+  return { headers, url };
+}
+
+/**
+ * @internal
+ *
+ * `AzureKMSRequestOptions` allows prose tests to modify the http request sent to the idms
+ * servers.  This is required to simulate different server conditions.  No options are expected to
+ * be set outside of tests.
+ *
+ * exposed for CSFLE
+ * [prose test 18](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/tests#azure-imds-credentials)
+ */
+export async function fetchAzureKMSToken(
+  options: AzureKMSRequestOptions = {}
+): Promise<AzureTokenCacheEntry> {
+  const { headers, url } = prepareRequest(options);
+  try {
+    const response = await get(url, { headers });
+    return await parseResponse(response);
+  } catch (error) {
+    if (error instanceof MongoNetworkTimeoutError) {
+      throw new MongoCryptAzureKMSRequestError(`[Azure KMS] ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * @internal
+ *
+ * @throws Will reject with a `MongoCryptError` if the http request fails or the http response is malformed.
+ */
+export async function loadAzureCredentials(kmsProviders: KMSProviders): Promise<KMSProviders> {
+  const azure = await tokenCache.getToken();
+  return { ...kmsProviders, azure };
+}

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

@@ -0,0 +1,16 @@
+import { getGcpMetadata } from '../../deps';
+import { type KMSProviders } from '.';
+
+/** @internal */
+export async function loadGCPCredentials(kmsProviders: KMSProviders): Promise<KMSProviders> {
+  const gcpMetadata = getGcpMetadata();
+
+  if ('kModuleError' in gcpMetadata) {
+    return kmsProviders;
+  }
+
+  const { access_token: accessToken } = await gcpMetadata.instance<{ access_token: string }>({
+    property: 'service-accounts/default/token'
+  });
+  return { ...kmsProviders, gcp: { accessToken } };
+}

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

@@ -0,0 +1,207 @@
+import type { Binary } from '../../bson';
+import { type AWSCredentialProvider } from '../../cmap/auth/aws_temporary_credentials';
+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 = 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 for custom credential providers for KMS requests.
+ */
+export interface CredentialProviders {
+  /* A custom AWS credential provider */
+  aws?: AWSCredentialProvider;
+}
+
+/**
+ * @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?: AWSKMSProviderConfiguration | Record<string, never>;
+  [key: `aws:${string}`]: AWSKMSProviderConfiguration;
+
+  /**
+   * Configuration options for using 'local' as your KMS provider
+   */
+  local?: LocalKMSProviderConfiguration;
+  [key: `local:${string}`]: LocalKMSProviderConfiguration;
+
+  /**
+   * Configuration options for using 'kmip' as your KMS provider
+   */
+  kmip?: KMIPKMSProviderConfiguration;
+  [key: `kmip:${string}`]: KMIPKMSProviderConfiguration;
+
+  /**
+   * Configuration options for using 'azure' as your KMS provider
+   */
+  azure?: AzureKMSProviderConfiguration | Record<string, never>;
+  [key: `azure:${string}`]: AzureKMSProviderConfiguration;
+
+  /**
+   * Configuration options for using 'gcp' as your KMS provider
+   */
+  gcp?: GCPKMSProviderConfiguration | Record<string, never>;
+  [key: `gcp:${string}`]: GCPKMSProviderConfiguration;
+}
+
+/**
+ * Auto credential fetching should only occur when the provider is defined on the kmsProviders map
+ * and the settings are an empty object.
+ *
+ * This is distinct from a nullish provider key.
+ *
+ * @internal - exposed for testing purposes only
+ */
+export function isEmptyCredentials(
+  providerName: ClientEncryptionDataKeyProvider,
+  kmsProviders: KMSProviders
+): boolean {
+  const provider = kmsProviders[providerName];
+  if (provider == null) {
+    return false;
+  }
+  return typeof provider === 'object' && Object.keys(provider).length === 0;
+}
+
+/**
+ * Load cloud provider credentials for the user provided KMS providers.
+ * Credentials will only attempt to get loaded if they do not exist
+ * and no existing credentials will get overwritten.
+ *
+ * @internal
+ */
+export async function refreshKMSCredentials(
+  kmsProviders: KMSProviders,
+  credentialProviders?: CredentialProviders
+): Promise<KMSProviders> {
+  let finalKMSProviders = kmsProviders;
+
+  if (isEmptyCredentials('aws', kmsProviders)) {
+    finalKMSProviders = await loadAWSCredentials(finalKMSProviders, credentialProviders?.aws);
+  }
+
+  if (isEmptyCredentials('gcp', kmsProviders)) {
+    finalKMSProviders = await loadGCPCredentials(finalKMSProviders);
+  }
+
+  if (isEmptyCredentials('azure', kmsProviders)) {
+    finalKMSProviders = await loadAzureCredentials(finalKMSProviders);
+  }
+  return finalKMSProviders;
+}