@depup/mongodb 7.1.0-depup.0

package/src/cmap/auth/mongo_credentials.ts

@@ -0,0 +1,292 @@
+// Resolves the default auth mechanism according to
+// Resolves the default auth mechanism according to
+import type { Document } from '../../bson';
+import {
+  MongoAPIError,
+  MongoInvalidArgumentError,
+  MongoMissingCredentialsError
+} from '../../error';
+import type { AWSCredentialProvider } from './aws_temporary_credentials';
+import { GSSAPICanonicalizationValue } from './gssapi';
+import type { OIDCCallbackFunction } from './mongodb_oidc';
+import { AUTH_MECHS_AUTH_SRC_EXTERNAL, AuthMechanism } from './providers';
+
+/**
+ * @see https://github.com/mongodb/specifications/blob/master/source/auth/auth.md
+ */
+function getDefaultAuthMechanism(hello: Document | null): AuthMechanism {
+  if (hello) {
+    // If hello contains saslSupportedMechs, use scram-sha-256
+    // if it is available, else scram-sha-1
+    if (Array.isArray(hello.saslSupportedMechs)) {
+      return hello.saslSupportedMechs.includes(AuthMechanism.MONGODB_SCRAM_SHA256)
+        ? AuthMechanism.MONGODB_SCRAM_SHA256
+        : AuthMechanism.MONGODB_SCRAM_SHA1;
+    }
+  }
+
+  // Default auth mechanism for 4.0 and higher.
+  return AuthMechanism.MONGODB_SCRAM_SHA256;
+}
+
+const ALLOWED_ENVIRONMENT_NAMES: AuthMechanismProperties['ENVIRONMENT'][] = [
+  'test',
+  'azure',
+  'gcp',
+  'k8s'
+];
+const ALLOWED_HOSTS_ERROR = 'Auth mechanism property ALLOWED_HOSTS must be an array of strings.';
+
+/** @internal */
+export const DEFAULT_ALLOWED_HOSTS = [
+  '*.mongodb.net',
+  '*.mongodb-qa.net',
+  '*.mongodb-dev.net',
+  '*.mongodbgov.net',
+  'localhost',
+  '127.0.0.1',
+  '::1',
+  '*.mongo.com'
+];
+
+/** Error for when the token audience is missing in the environment. */
+const TOKEN_RESOURCE_MISSING_ERROR =
+  'TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is azure or gcp.';
+
+/** @public */
+export interface AuthMechanismProperties extends Document {
+  SERVICE_HOST?: string;
+  SERVICE_NAME?: string;
+  SERVICE_REALM?: string;
+  CANONICALIZE_HOST_NAME?: GSSAPICanonicalizationValue;
+  /** @internal */
+  AWS_SESSION_TOKEN?: string;
+  /** A user provided OIDC machine callback function. */
+  OIDC_CALLBACK?: OIDCCallbackFunction;
+  /** A user provided OIDC human interacted callback function. */
+  OIDC_HUMAN_CALLBACK?: OIDCCallbackFunction;
+  /** The OIDC environment. Note that 'test' is for internal use only. */
+  ENVIRONMENT?: 'test' | 'azure' | 'gcp' | 'k8s';
+  /** Allowed hosts that OIDC auth can connect to. */
+  ALLOWED_HOSTS?: string[];
+  /** The resource token for OIDC auth in Azure and GCP. */
+  TOKEN_RESOURCE?: string;
+  /**
+   * A custom AWS credential provider to use. An example using the AWS SDK default provider chain:
+   *
+   * ```ts
+   * const client = new MongoClient(process.env.MONGODB_URI, {
+   *   authMechanismProperties: {
+   *     AWS_CREDENTIAL_PROVIDER: fromNodeProviderChain()
+   *   }
+   * });
+   * ```
+   *
+   * Using a custom function that returns AWS credentials:
+   *
+   * ```ts
+   * const client = new MongoClient(process.env.MONGODB_URI, {
+   *   authMechanismProperties: {
+   *     AWS_CREDENTIAL_PROVIDER: async () => {
+   *       return {
+   *         accessKeyId: process.env.ACCESS_KEY_ID,
+   *         secretAccessKey: process.env.SECRET_ACCESS_KEY
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  AWS_CREDENTIAL_PROVIDER?: AWSCredentialProvider;
+}
+
+/** @public */
+export interface MongoCredentialsOptions {
+  username?: string;
+  password: string;
+  source: string;
+  db?: string;
+  mechanism?: AuthMechanism;
+  mechanismProperties: AuthMechanismProperties;
+}
+
+/**
+ * A representation of the credentials used by MongoDB
+ * @public
+ */
+export class MongoCredentials {
+  /** The username used for authentication */
+  readonly username: string;
+  /** The password used for authentication */
+  readonly password: string;
+  /** The database that the user should authenticate against */
+  readonly source: string;
+  /** The method used to authenticate */
+  readonly mechanism: AuthMechanism;
+  /** Special properties used by some types of auth mechanisms */
+  readonly mechanismProperties: AuthMechanismProperties;
+
+  constructor(options: MongoCredentialsOptions) {
+    this.username = options.username ?? '';
+    this.password = options.password;
+    this.source = options.source;
+    if (!this.source && options.db) {
+      this.source = options.db;
+    }
+    this.mechanism = options.mechanism || AuthMechanism.MONGODB_DEFAULT;
+    this.mechanismProperties = options.mechanismProperties || {};
+
+    if (this.mechanism === AuthMechanism.MONGODB_OIDC && !this.mechanismProperties.ALLOWED_HOSTS) {
+      this.mechanismProperties = {
+        ...this.mechanismProperties,
+        ALLOWED_HOSTS: DEFAULT_ALLOWED_HOSTS
+      };
+    }
+
+    Object.freeze(this.mechanismProperties);
+    Object.freeze(this);
+  }
+
+  /** Determines if two MongoCredentials objects are equivalent */
+  equals(other: MongoCredentials): boolean {
+    return (
+      this.mechanism === other.mechanism &&
+      this.username === other.username &&
+      this.password === other.password &&
+      this.source === other.source
+    );
+  }
+
+  /**
+   * If the authentication mechanism is set to "default", resolves the authMechanism
+   * based on the server version and server supported sasl mechanisms.
+   *
+   * @param hello - A hello response from the server
+   */
+  resolveAuthMechanism(hello: Document | null): MongoCredentials {
+    // If the mechanism is not "default", then it does not need to be resolved
+    if (this.mechanism.match(/DEFAULT/i)) {
+      return new MongoCredentials({
+        username: this.username,
+        password: this.password,
+        source: this.source,
+        mechanism: getDefaultAuthMechanism(hello),
+        mechanismProperties: this.mechanismProperties
+      });
+    }
+
+    return this;
+  }
+
+  validate(): void {
+    if (
+      (this.mechanism === AuthMechanism.MONGODB_GSSAPI ||
+        this.mechanism === AuthMechanism.MONGODB_PLAIN ||
+        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA1 ||
+        this.mechanism === AuthMechanism.MONGODB_SCRAM_SHA256) &&
+      !this.username
+    ) {
+      throw new MongoMissingCredentialsError(`Username required for mechanism '${this.mechanism}'`);
+    }
+
+    if (this.mechanism === AuthMechanism.MONGODB_OIDC) {
+      if (
+        this.username &&
+        this.mechanismProperties.ENVIRONMENT &&
+        this.mechanismProperties.ENVIRONMENT !== 'azure'
+      ) {
+        throw new MongoInvalidArgumentError(
+          `username and ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' may not be used together for mechanism '${this.mechanism}'.`
+        );
+      }
+
+      if (this.username && this.password) {
+        throw new MongoInvalidArgumentError(
+          `No password is allowed in ENVIRONMENT '${this.mechanismProperties.ENVIRONMENT}' for '${this.mechanism}'.`
+        );
+      }
+
+      if (
+        (this.mechanismProperties.ENVIRONMENT === 'azure' ||
+          this.mechanismProperties.ENVIRONMENT === 'gcp') &&
+        !this.mechanismProperties.TOKEN_RESOURCE
+      ) {
+        throw new MongoInvalidArgumentError(TOKEN_RESOURCE_MISSING_ERROR);
+      }
+
+      if (
+        this.mechanismProperties.ENVIRONMENT &&
+        !ALLOWED_ENVIRONMENT_NAMES.includes(this.mechanismProperties.ENVIRONMENT)
+      ) {
+        throw new MongoInvalidArgumentError(
+          `Currently only a ENVIRONMENT in ${ALLOWED_ENVIRONMENT_NAMES.join(
+            ','
+          )} is supported for mechanism '${this.mechanism}'.`
+        );
+      }
+
+      if (
+        !this.mechanismProperties.ENVIRONMENT &&
+        !this.mechanismProperties.OIDC_CALLBACK &&
+        !this.mechanismProperties.OIDC_HUMAN_CALLBACK
+      ) {
+        throw new MongoInvalidArgumentError(
+          `Either a ENVIRONMENT, OIDC_CALLBACK, or OIDC_HUMAN_CALLBACK must be specified for mechanism '${this.mechanism}'.`
+        );
+      }
+
+      if (this.mechanismProperties.ALLOWED_HOSTS) {
+        const hosts = this.mechanismProperties.ALLOWED_HOSTS;
+        if (!Array.isArray(hosts)) {
+          throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
+        }
+        for (const host of hosts) {
+          if (typeof host !== 'string') {
+            throw new MongoInvalidArgumentError(ALLOWED_HOSTS_ERROR);
+          }
+        }
+      }
+    }
+
+    if (AUTH_MECHS_AUTH_SRC_EXTERNAL.has(this.mechanism)) {
+      if (this.source != null && this.source !== '$external') {
+        // TODO(NODE-3485): Replace this with a MongoAuthValidationError
+        throw new MongoAPIError(
+          `Invalid source '${this.source}' for mechanism '${this.mechanism}' specified.`
+        );
+      }
+    }
+
+    if (this.mechanism === AuthMechanism.MONGODB_PLAIN && this.source == null) {
+      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
+      throw new MongoAPIError('PLAIN Authentication Mechanism needs an auth source');
+    }
+
+    if (this.mechanism === AuthMechanism.MONGODB_X509 && this.password != null) {
+      if (this.password === '') {
+        Reflect.set(this, 'password', undefined);
+        return;
+      }
+      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
+      throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
+    }
+
+    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
+    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {
+      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
+    }
+  }
+
+  static merge(
+    creds: MongoCredentials | undefined,
+    options: Partial<MongoCredentialsOptions>
+  ): MongoCredentials {
+    return new MongoCredentials({
+      username: options.username ?? creds?.username ?? '',
+      password: options.password ?? creds?.password ?? '',
+      mechanism: options.mechanism ?? creds?.mechanism ?? AuthMechanism.MONGODB_DEFAULT,
+      mechanismProperties: options.mechanismProperties ?? creds?.mechanismProperties ?? {},
+      source: options.source ?? options.db ?? creds?.source ?? 'admin'
+    });
+  }
+}

package/src/cmap/auth/mongodb_aws.ts

@@ -0,0 +1,179 @@
+import type { Binary, BSONSerializeOptions } from '../../bson';
+import * as BSON from '../../bson';
+import {
+  MongoCompatibilityError,
+  MongoMissingCredentialsError,
+  MongoRuntimeError
+} from '../../error';
+import { ByteUtils, maxWireVersion, ns, randomBytes } from '../../utils';
+import { type AuthContext, AuthProvider } from './auth_provider';
+import {
+  type AWSCredentialProvider,
+  AWSSDKCredentialProvider,
+  type AWSTempCredentials
+} from './aws_temporary_credentials';
+import { aws4Sign } from './aws4';
+import { MongoCredentials } from './mongo_credentials';
+import { AuthMechanism } from './providers';
+
+const ASCII_N = 110;
+const bsonOptions: BSONSerializeOptions = {
+  useBigInt64: false,
+  promoteLongs: true,
+  promoteValues: true,
+  promoteBuffers: false,
+  bsonRegExp: false
+};
+
+interface AWSSaslContinuePayload {
+  a: string;
+  d: string;
+  t?: string;
+}
+
+export class MongoDBAWS extends AuthProvider {
+  private credentialFetcher: AWSSDKCredentialProvider;
+
+  constructor(credentialProvider?: AWSCredentialProvider) {
+    super();
+    this.credentialFetcher = new AWSSDKCredentialProvider(credentialProvider);
+  }
+
+  override async auth(authContext: AuthContext): Promise<void> {
+    const { connection } = authContext;
+    if (!authContext.credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+
+    if (maxWireVersion(connection) < 9) {
+      throw new MongoCompatibilityError(
+        'MONGODB-AWS authentication requires MongoDB version 4.4 or later'
+      );
+    }
+
+    authContext.credentials = await makeTempCredentials(
+      authContext.credentials,
+      this.credentialFetcher
+    );
+
+    const { credentials } = authContext;
+
+    const accessKeyId = credentials.username;
+    const secretAccessKey = credentials.password;
+    // Allow the user to specify an AWS session token for authentication with temporary credentials.
+    const sessionToken = credentials.mechanismProperties.AWS_SESSION_TOKEN;
+
+    // If all three defined, include sessionToken, else only include username and pass
+    const awsCredentials = sessionToken
+      ? { accessKeyId, secretAccessKey, sessionToken }
+      : { accessKeyId, secretAccessKey };
+
+    const db = credentials.source;
+    const nonce = await randomBytes(32);
+
+    // All messages between MongoDB clients and servers are sent as BSON objects
+    // in the payload field of saslStart and saslContinue.
+    const saslStart = {
+      saslStart: 1,
+      mechanism: 'MONGODB-AWS',
+      payload: BSON.serialize({ r: nonce, p: ASCII_N }, bsonOptions)
+    };
+
+    const saslStartResponse = await connection.command(ns(`${db}.$cmd`), saslStart, undefined);
+
+    const serverResponse = BSON.deserialize(saslStartResponse.payload.buffer, bsonOptions) as {
+      s: Binary;
+      h: string;
+    };
+    const host = serverResponse.h;
+    const serverNonce = serverResponse.s.buffer;
+    if (serverNonce.length !== 64) {
+      // TODO(NODE-3483)
+      throw new MongoRuntimeError(`Invalid server nonce length ${serverNonce.length}, expected 64`);
+    }
+
+    if (!ByteUtils.equals(serverNonce.subarray(0, nonce.byteLength), nonce)) {
+      // throw because the serverNonce's leading 32 bytes must equal the client nonce's 32 bytes
+      // https://github.com/mongodb/specifications/blob/master/source/auth/auth.md#conversation-5
+
+      // TODO(NODE-3483)
+      throw new MongoRuntimeError('Server nonce does not begin with client nonce');
+    }
+
+    if (host.length < 1 || host.length > 255 || host.indexOf('..') !== -1) {
+      // TODO(NODE-3483)
+      throw new MongoRuntimeError(`Server returned an invalid host: "${host}"`);
+    }
+
+    const body = 'Action=GetCallerIdentity&Version=2011-06-15';
+    const headers = await aws4Sign(
+      {
+        method: 'POST',
+        host,
+        region: deriveRegion(serverResponse.h),
+        service: 'sts',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': body.length,
+          'X-MongoDB-Server-Nonce': ByteUtils.toBase64(serverNonce),
+          'X-MongoDB-GS2-CB-Flag': 'n'
+        },
+        path: '/',
+        body,
+        date: new Date()
+      },
+      awsCredentials
+    );
+
+    const payload: AWSSaslContinuePayload = {
+      a: headers.Authorization,
+      d: headers['X-Amz-Date']
+    };
+
+    if (sessionToken) {
+      payload.t = sessionToken;
+    }
+
+    const saslContinue = {
+      saslContinue: 1,
+      conversationId: saslStartResponse.conversationId,
+      payload: BSON.serialize(payload, bsonOptions)
+    };
+
+    await connection.command(ns(`${db}.$cmd`), saslContinue, undefined);
+  }
+}
+
+async function makeTempCredentials(
+  credentials: MongoCredentials,
+  awsCredentialFetcher: AWSSDKCredentialProvider
+): Promise<MongoCredentials> {
+  function makeMongoCredentialsFromAWSTemp(creds: AWSTempCredentials) {
+    // The AWS session token (creds.Token) may or may not be set.
+    if (!creds.AccessKeyId || !creds.SecretAccessKey) {
+      throw new MongoMissingCredentialsError('Could not obtain temporary MONGODB-AWS credentials');
+    }
+
+    return new MongoCredentials({
+      username: creds.AccessKeyId,
+      password: creds.SecretAccessKey,
+      source: credentials.source,
+      mechanism: AuthMechanism.MONGODB_AWS,
+      mechanismProperties: {
+        AWS_SESSION_TOKEN: creds.Token
+      }
+    });
+  }
+  const temporaryCredentials = await awsCredentialFetcher.getCredentials();
+
+  return makeMongoCredentialsFromAWSTemp(temporaryCredentials);
+}
+
+function deriveRegion(host: string) {
+  const parts = host.split('.');
+  if (parts.length === 1 || parts[1] === 'amazonaws') {
+    return 'us-east-1';
+  }
+
+  return parts[1];
+}

package/src/cmap/auth/mongodb_oidc/automated_callback_workflow.ts

@@ -0,0 +1,88 @@
+import { MONGODB_ERROR_CODES, MongoError, MongoOIDCError } from '../../../error';
+import { Timeout, TimeoutError } from '../../../timeout';
+import { type Connection } from '../../connection';
+import { type MongoCredentials } from '../mongo_credentials';
+import {
+  OIDC_VERSION,
+  type OIDCCallbackFunction,
+  type OIDCCallbackParams,
+  type OIDCResponse
+} from '../mongodb_oidc';
+import { AUTOMATED_TIMEOUT_MS, CallbackWorkflow } from './callback_workflow';
+import { type TokenCache } from './token_cache';
+
+/**
+ * Class implementing behaviour for the non human callback workflow.
+ * @internal
+ */
+export class AutomatedCallbackWorkflow extends CallbackWorkflow {
+  /**
+   * Instantiate the human callback workflow.
+   */
+  constructor(cache: TokenCache, callback: OIDCCallbackFunction) {
+    super(cache, callback);
+  }
+
+  /**
+   * Execute the OIDC callback workflow.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    // If there is a cached access token, try to authenticate with it. If
+    // authentication fails with an Authentication error (18),
+    // invalidate the access token, fetch a new access token, and try
+    // to authenticate again.
+    // If the server fails for any other reason, do not clear the cache.
+    if (this.cache.hasAccessToken) {
+      const token = this.cache.getAccessToken();
+      if (!connection.accessToken) {
+        connection.accessToken = token;
+      }
+      try {
+        return await this.finishAuthentication(connection, credentials, token);
+      } catch (error) {
+        if (
+          error instanceof MongoError &&
+          error.code === MONGODB_ERROR_CODES.AuthenticationFailed
+        ) {
+          this.cache.removeAccessToken();
+          return await this.execute(connection, credentials);
+        } else {
+          throw error;
+        }
+      }
+    }
+    const response = await this.fetchAccessToken(credentials);
+    this.cache.put(response);
+    connection.accessToken = response.accessToken;
+    await this.finishAuthentication(connection, credentials, response.accessToken);
+  }
+
+  /**
+   * Fetches the access token using the callback.
+   */
+  protected async fetchAccessToken(credentials: MongoCredentials): Promise<OIDCResponse> {
+    const controller = new AbortController();
+    const params: OIDCCallbackParams = {
+      timeoutContext: controller.signal,
+      version: OIDC_VERSION
+    };
+    if (credentials.username) {
+      params.username = credentials.username;
+    }
+    if (credentials.mechanismProperties.TOKEN_RESOURCE) {
+      params.tokenAudience = credentials.mechanismProperties.TOKEN_RESOURCE;
+    }
+    const timeout = Timeout.expires(AUTOMATED_TIMEOUT_MS);
+    try {
+      return await Promise.race([this.executeAndValidateCallback(params), timeout]);
+    } catch (error) {
+      if (TimeoutError.is(error)) {
+        controller.abort();
+        throw new MongoOIDCError(`OIDC callback timed out after ${AUTOMATED_TIMEOUT_MS}ms.`);
+      }
+      throw error;
+    } finally {
+      timeout.clear();
+    }
+  }
+}

package/src/cmap/auth/mongodb_oidc/azure_machine_workflow.ts

@@ -0,0 +1,73 @@
+import { addAzureParams, AZURE_BASE_URL } from '../../../client-side-encryption/providers/azure';
+import { MongoAzureError } from '../../../error';
+import { get } from '../../../utils';
+import type { OIDCCallbackFunction, OIDCCallbackParams, OIDCResponse } from '../mongodb_oidc';
+
+/** Azure request headers. */
+const AZURE_HEADERS = Object.freeze({ Metadata: 'true', Accept: 'application/json' });
+
+/** Invalid endpoint result error. */
+const ENDPOINT_RESULT_ERROR =
+  'Azure endpoint did not return a value with only access_token and expires_in properties';
+
+/** Error for when the token audience is missing in the environment. */
+const TOKEN_RESOURCE_MISSING_ERROR =
+  'TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is azure.';
+
+/**
+ * The callback function to be used in the automated callback workflow.
+ * @param params - The OIDC callback parameters.
+ * @returns The OIDC response.
+ */
+export const callback: OIDCCallbackFunction = async (
+  params: OIDCCallbackParams
+): Promise<OIDCResponse> => {
+  const tokenAudience = params.tokenAudience;
+  const username = params.username;
+  if (!tokenAudience) {
+    throw new MongoAzureError(TOKEN_RESOURCE_MISSING_ERROR);
+  }
+  const response = await getAzureTokenData(tokenAudience, username);
+  if (!isEndpointResultValid(response)) {
+    throw new MongoAzureError(ENDPOINT_RESULT_ERROR);
+  }
+  return response;
+};
+
+/**
+ * Hit the Azure endpoint to get the token data.
+ */
+async function getAzureTokenData(tokenAudience: string, username?: string): Promise<OIDCResponse> {
+  const url = new URL(AZURE_BASE_URL);
+  addAzureParams(url, tokenAudience, username);
+  const response = await get(url, {
+    headers: AZURE_HEADERS
+  });
+  if (response.status !== 200) {
+    throw new MongoAzureError(
+      `Status code ${response.status} returned from the Azure endpoint. Response body: ${response.body}`
+    );
+  }
+  const result = JSON.parse(response.body);
+  return {
+    accessToken: result.access_token,
+    expiresInSeconds: Number(result.expires_in)
+  };
+}
+
+/**
+ * Determines if a result returned from the endpoint is valid.
+ * This means the result is not nullish, contains the access_token required field
+ * and the expires_in required field.
+ */
+function isEndpointResultValid(
+  token: unknown
+): token is { access_token: unknown; expires_in: unknown } {
+  if (token == null || typeof token !== 'object') return false;
+  return (
+    'accessToken' in token &&
+    typeof token.accessToken === 'string' &&
+    'expiresInSeconds' in token &&
+    typeof token.expiresInSeconds === 'number'
+  );
+}