mongodb 6.6.2 → 6.7.0

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

@@ -0,0 +1,137 @@
+import { type Document } from 'bson';
+import { setTimeout } from 'timers/promises';
+
+import { ns } from '../../../utils';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import type { Workflow } from '../mongodb_oidc';
+import { finishCommandDocument } from './command_builders';
+import { type TokenCache } from './token_cache';
+
+/** The time to throttle callback calls. */
+const THROTTLE_MS = 100;
+
+/**
+ * The access token format.
+ * @internal
+ */
+export interface AccessToken {
+  access_token: string;
+  expires_in?: number;
+}
+
+/** @internal */
+export type OIDCTokenFunction = (credentials: MongoCredentials) => Promise<AccessToken>;
+
+/**
+ * Common behaviour for OIDC machine workflows.
+ * @internal
+ */
+export abstract class MachineWorkflow implements Workflow {
+  cache: TokenCache;
+  callback: OIDCTokenFunction;
+  lastExecutionTime: number;
+
+  /**
+   * Instantiate the machine workflow.
+   */
+  constructor(cache: TokenCache) {
+    this.cache = cache;
+    this.callback = this.withLock(this.getToken.bind(this));
+    this.lastExecutionTime = Date.now() - THROTTLE_MS;
+  }
+
+  /**
+   * Execute the workflow. Gets the token from the subclass implementation.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    const token = await this.getTokenFromCacheOrEnv(connection, credentials);
+    const command = finishCommandDocument(token);
+    await connection.command(ns(credentials.source), command, undefined);
+  }
+
+  /**
+   * Reauthenticate on a machine workflow just grabs the token again since the server
+   * has said the current access token is invalid or expired.
+   */
+  async reauthenticate(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    if (this.cache.hasAccessToken) {
+      // Reauthentication implies the token has expired.
+      if (connection.accessToken === this.cache.getAccessToken()) {
+        // If connection's access token is the same as the cache's, remove
+        // the token from the cache and connection.
+        this.cache.removeAccessToken();
+        delete connection.accessToken;
+      } else {
+        // If the connection's access token is different from the cache's, set
+        // the cache's token on the connection and do not remove from the
+        // cache.
+        connection.accessToken = this.cache.getAccessToken();
+      }
+    }
+    await this.execute(connection, credentials);
+  }
+
+  /**
+   * Get the document to add for speculative authentication.
+   */
+  async speculativeAuth(connection: Connection, credentials: MongoCredentials): Promise<Document> {
+    // The spec states only cached access tokens can use speculative auth.
+    if (!this.cache.hasAccessToken) {
+      return {};
+    }
+    const token = await this.getTokenFromCacheOrEnv(connection, credentials);
+    const document = finishCommandDocument(token);
+    document.db = credentials.source;
+    return { speculativeAuthenticate: document };
+  }
+
+  /**
+   * Get the token from the cache or environment.
+   */
+  private async getTokenFromCacheOrEnv(
+    connection: Connection,
+    credentials: MongoCredentials
+  ): Promise<string> {
+    if (this.cache.hasAccessToken) {
+      return this.cache.getAccessToken();
+    } else {
+      const token = await this.callback(credentials);
+      this.cache.put({ accessToken: token.access_token, expiresInSeconds: token.expires_in });
+      // Put the access token on the connection as well.
+      connection.accessToken = token.access_token;
+      return token.access_token;
+    }
+  }
+
+  /**
+   * Ensure the callback is only executed one at a time, and throttled to
+   * only once per 100ms.
+   */
+  private withLock(callback: OIDCTokenFunction): OIDCTokenFunction {
+    let lock: Promise<any> = Promise.resolve();
+    return async (credentials: MongoCredentials): Promise<AccessToken> => {
+      // We do this to ensure that we would never return the result of the
+      // previous lock, only the current callback's value would get returned.
+      await lock;
+      lock = lock
+        // eslint-disable-next-line github/no-then
+        .catch(() => null)
+        // eslint-disable-next-line github/no-then
+        .then(async () => {
+          const difference = Date.now() - this.lastExecutionTime;
+          if (difference <= THROTTLE_MS) {
+            await setTimeout(THROTTLE_MS - difference);
+          }
+          this.lastExecutionTime = Date.now();
+          return await callback(credentials);
+        });
+      return await lock;
+    };
+  }
+
+  /**
+   * Get the token from the environment or endpoint.
+   */
+  abstract getToken(credentials: MongoCredentials): Promise<AccessToken>;
+}

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

@@ -0,0 +1,62 @@
+import { MongoDriverError } from '../../../error';
+import type { IdPInfo, OIDCResponse } from '../mongodb_oidc';
+
+class MongoOIDCError extends MongoDriverError {}
+
+/** @internal */
+export class TokenCache {
+  private accessToken?: string;
+  private refreshToken?: string;
+  private idpInfo?: IdPInfo;
+  private expiresInSeconds?: number;
+
+  get hasAccessToken(): boolean {
+    return !!this.accessToken;
+  }
+
+  get hasRefreshToken(): boolean {
+    return !!this.refreshToken;
+  }
+
+  get hasIdpInfo(): boolean {
+    return !!this.idpInfo;
+  }
+
+  getAccessToken(): string {
+    if (!this.accessToken) {
+      throw new MongoOIDCError('Attempted to get an access token when none exists.');
+    }
+    return this.accessToken;
+  }
+
+  getRefreshToken(): string {
+    if (!this.refreshToken) {
+      throw new MongoOIDCError('Attempted to get a refresh token when none exists.');
+    }
+    return this.refreshToken;
+  }
+
+  getIdpInfo(): IdPInfo {
+    if (!this.idpInfo) {
+      throw new MongoOIDCError('Attempted to get IDP information when none exists.');
+    }
+    return this.idpInfo;
+  }
+
+  put(response: OIDCResponse, idpInfo?: IdPInfo) {
+    this.accessToken = response.accessToken;
+    this.refreshToken = response.refreshToken;
+    this.expiresInSeconds = response.expiresInSeconds;
+    if (idpInfo) {
+      this.idpInfo = idpInfo;
+    }
+  }
+
+  removeAccessToken() {
+    this.accessToken = undefined;
+  }
+
+  removeRefreshToken() {
+    this.refreshToken = undefined;
+  }
+}

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

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+
+import { MongoAWSError } from '../../../error';
+import { type AccessToken, MachineWorkflow } from './machine_workflow';
+import { type TokenCache } from './token_cache';
+
+/** Error for when the token is missing in the environment. */
+const TOKEN_MISSING_ERROR = 'OIDC_TOKEN_FILE must be set in the environment.';
+
+/**
+ * Device workflow implementation for AWS.
+ *
+ * @internal
+ */
+export class TokenMachineWorkflow extends MachineWorkflow {
+  /**
+   * Instantiate the machine workflow.
+   */
+  constructor(cache: TokenCache) {
+    super(cache);
+  }
+
+  /**
+   * Get the token from the environment.
+   */
+  async getToken(): Promise<AccessToken> {
+    const tokenFile = process.env.OIDC_TOKEN_FILE;
+    if (!tokenFile) {
+      throw new MongoAWSError(TOKEN_MISSING_ERROR);
+    }
+    const token = await fs.promises.readFile(tokenFile, 'utf8');
+    return { access_token: token };
+  }
+}

package/src/cmap/auth/mongodb_oidc.ts

@@ -5,64 +5,93 @@ import type { HandshakeDocument } from '../connect';
 import type { Connection } from '../connection';
 import { type AuthContext, AuthProvider } from './auth_provider';
 import type { MongoCredentials } from './mongo_credentials';
-import { AwsServiceWorkflow } from './mongodb_oidc/aws_service_workflow';
-import { AzureServiceWorkflow } from './mongodb_oidc/azure_service_workflow';
-import { CallbackWorkflow } from './mongodb_oidc/callback_workflow';
+import { AzureMachineWorkflow } from './mongodb_oidc/azure_machine_workflow';
+import { GCPMachineWorkflow } from './mongodb_oidc/gcp_machine_workflow';
+import { TokenCache } from './mongodb_oidc/token_cache';
+import { TokenMachineWorkflow } from './mongodb_oidc/token_machine_workflow';
 
 /** Error when credentials are missing. */
 const MISSING_CREDENTIALS_ERROR = 'AuthContext must provide credentials.';
 
 /**
+ * The information returned by the server on the IDP server.
  * @public
- * @experimental
  */
-export interface IdPServerInfo {
+export interface IdPInfo {
+  /**
+   * A URL which describes the Authentication Server. This identifier should
+   * be the iss of provided access tokens, and be viable for RFC8414 metadata
+   * discovery and RFC9207 identification.
+   */
   issuer: string;
+  /** A unique client ID for this OIDC client. */
   clientId: string;
+  /** A list of additional scopes to request from IdP. */
   requestScopes?: string[];
 }
 
 /**
+ * The response from the IdP server with the access token and
+ * optional expiration time and refresh token.
  * @public
- * @experimental
  */
 export interface IdPServerResponse {
+  /** The OIDC access token. */
   accessToken: string;
+  /** The time when the access token expires. For future use. */
   expiresInSeconds?: number;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
   refreshToken?: string;
 }
 
 /**
+ * The response required to be returned from the machine or
+ * human callback workflows' callback.
  * @public
- * @experimental
  */
-export interface OIDCCallbackContext {
+export interface OIDCResponse {
+  /** The OIDC access token. */
+  accessToken: string;
+  /** The time when the access token expires. For future use. */
+  expiresInSeconds?: number;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
   refreshToken?: string;
-  timeoutSeconds?: number;
-  timeoutContext?: AbortSignal;
-  version: number;
 }
 
 /**
+ * The parameters that the driver provides to the user supplied
+ * human or machine callback.
+ *
+ * The version number is used to communicate callback API changes that are not breaking but that
+ * users may want to know about and review their implementation. Users may wish to check the version
+ * number and throw an error if their expected version number and the one provided do not match.
  * @public
- * @experimental
  */
-export type OIDCRequestFunction = (
-  info: IdPServerInfo,
-  context: OIDCCallbackContext
-) => Promise<IdPServerResponse>;
+export interface OIDCCallbackParams {
+  /** Optional username. */
+  username?: string;
+  /** The context in which to timeout the OIDC callback. */
+  timeoutContext: AbortSignal;
+  /** The current OIDC API version. */
+  version: 1;
+  /** The IdP information returned from the server. */
+  idpInfo?: IdPInfo;
+  /** The refresh token, if applicable, to be used by the callback to request a new token from the issuer. */
+  refreshToken?: string;
+}
 
 /**
+ * The signature of the human or machine callback functions.
  * @public
- * @experimental
  */
-export type OIDCRefreshFunction = (
-  info: IdPServerInfo,
-  context: OIDCCallbackContext
-) => Promise<IdPServerResponse>;
+export type OIDCCallbackFunction = (params: OIDCCallbackParams) => Promise<OIDCResponse>;
+
+/** The current version of OIDC implementation. */
+export const OIDC_VERSION = 1;
 
-type ProviderName = 'aws' | 'azure' | 'callback';
+type EnvironmentName = 'test' | 'azure' | 'gcp' | undefined;
 
+/** @internal */
 export interface Workflow {
   /**
    * All device workflows must implement this method in order to get the access
@@ -71,32 +100,41 @@ export interface Workflow {
   execute(
     connection: Connection,
     credentials: MongoCredentials,
-    reauthenticating: boolean,
     response?: Document
-  ): Promise<Document>;
+  ): Promise<void>;
+
+  /**
+   * Each workflow should specify the correct custom behaviour for reauthentication.
+   */
+  reauthenticate(connection: Connection, credentials: MongoCredentials): Promise<void>;
 
   /**
    * Get the document to add for speculative authentication.
    */
-  speculativeAuth(credentials: MongoCredentials): Promise<Document>;
+  speculativeAuth(connection: Connection, credentials: MongoCredentials): Promise<Document>;
 }
 
 /** @internal */
-export const OIDC_WORKFLOWS: Map<ProviderName, Workflow> = new Map();
-OIDC_WORKFLOWS.set('callback', new CallbackWorkflow());
-OIDC_WORKFLOWS.set('aws', new AwsServiceWorkflow());
-OIDC_WORKFLOWS.set('azure', new AzureServiceWorkflow());
+export const OIDC_WORKFLOWS: Map<EnvironmentName, () => Workflow> = new Map();
+OIDC_WORKFLOWS.set('test', () => new TokenMachineWorkflow(new TokenCache()));
+OIDC_WORKFLOWS.set('azure', () => new AzureMachineWorkflow(new TokenCache()));
+OIDC_WORKFLOWS.set('gcp', () => new GCPMachineWorkflow(new TokenCache()));
 
 /**
  * OIDC auth provider.
- * @experimental
  */
 export class MongoDBOIDC extends AuthProvider {
+  workflow: Workflow;
+
   /**
    * Instantiate the auth provider.
    */
-  constructor() {
+  constructor(workflow?: Workflow) {
     super();
+    if (!workflow) {
+      throw new MongoInvalidArgumentError('No workflow provided to the OIDC auth provider.');
+    }
+    this.workflow = workflow;
   }
 
   /**
@@ -104,9 +142,15 @@ export class MongoDBOIDC extends AuthProvider {
    */
   override async auth(authContext: AuthContext): Promise<void> {
     const { connection, reauthenticating, response } = authContext;
+    if (response?.speculativeAuthenticate?.done) {
+      return;
+    }
     const credentials = getCredentials(authContext);
-    const workflow = getWorkflow(credentials);
-    await workflow.execute(connection, credentials, reauthenticating, response);
+    if (reauthenticating) {
+      await this.workflow.reauthenticate(connection, credentials);
+    } else {
+      await this.workflow.execute(connection, credentials, response);
+    }
   }
 
   /**
@@ -116,9 +160,9 @@ export class MongoDBOIDC extends AuthProvider {
     handshakeDoc: HandshakeDocument,
     authContext: AuthContext
   ): Promise<HandshakeDocument> {
+    const { connection } = authContext;
     const credentials = getCredentials(authContext);
-    const workflow = getWorkflow(credentials);
-    const result = await workflow.speculativeAuth(credentials);
+    const result = await this.workflow.speculativeAuth(connection, credentials);
     return { ...handshakeDoc, ...result };
   }
 }
@@ -133,17 +177,3 @@ function getCredentials(authContext: AuthContext): MongoCredentials {
   }
   return credentials;
 }
-
-/**
- * Gets either a device workflow or callback workflow.
- */
-function getWorkflow(credentials: MongoCredentials): Workflow {
-  const providerName = credentials.mechanismProperties.PROVIDER_NAME;
-  const workflow = OIDC_WORKFLOWS.get(providerName || 'callback');
-  if (!workflow) {
-    throw new MongoInvalidArgumentError(
-      `Could not load workflow for provider ${credentials.mechanismProperties.PROVIDER_NAME}`
-    );
-  }
-  return workflow;
-}

package/src/cmap/auth/providers.ts

@@ -8,7 +8,6 @@ export const AuthMechanism = Object.freeze({
   MONGODB_SCRAM_SHA1: 'SCRAM-SHA-1',
   MONGODB_SCRAM_SHA256: 'SCRAM-SHA-256',
   MONGODB_X509: 'MONGODB-X509',
-  /** @experimental */
   MONGODB_OIDC: 'MONGODB-OIDC'
 } as const);
 

package/src/cmap/connect.ts

@@ -91,7 +91,10 @@ export async function performInitialHandshake(
   if (credentials) {
     if (
       !(credentials.mechanism === AuthMechanism.MONGODB_DEFAULT) &&
-      !options.authProviders.getOrCreateProvider(credentials.mechanism)
+      !options.authProviders.getOrCreateProvider(
+        credentials.mechanism,
+        credentials.mechanismProperties
+      )
     ) {
       throw new MongoInvalidArgumentError(`AuthMechanism '${credentials.mechanism}' not supported`);
     }
@@ -146,7 +149,10 @@ export async function performInitialHandshake(
     authContext.response = response;
 
     const resolvedCredentials = credentials.resolveAuthMechanism(response);
-    const provider = options.authProviders.getOrCreateProvider(resolvedCredentials.mechanism);
+    const provider = options.authProviders.getOrCreateProvider(
+      resolvedCredentials.mechanism,
+      resolvedCredentials.mechanismProperties
+    );
     if (!provider) {
       throw new MongoInvalidArgumentError(
         `No AuthProvider for ${resolvedCredentials.mechanism} defined.`
@@ -218,7 +224,8 @@ export async function prepareHandshakeDocument(
       handshakeDoc.saslSupportedMechs = `${credentials.source}.${credentials.username}`;
 
       const provider = authContext.options.authProviders.getOrCreateProvider(
-        AuthMechanism.MONGODB_SCRAM_SHA256
+        AuthMechanism.MONGODB_SCRAM_SHA256,
+        credentials.mechanismProperties
       );
       if (!provider) {
         // This auth mechanism is always present.
@@ -228,7 +235,10 @@ export async function prepareHandshakeDocument(
       }
       return await provider.prepare(handshakeDoc, authContext);
     }
-    const provider = authContext.options.authProviders.getOrCreateProvider(credentials.mechanism);
+    const provider = authContext.options.authProviders.getOrCreateProvider(
+      credentials.mechanism,
+      credentials.mechanismProperties
+    );
     if (!provider) {
       throw new MongoInvalidArgumentError(`No AuthProvider for ${credentials.mechanism} defined.`);
     }

package/src/cmap/connection.ts

@@ -174,6 +174,7 @@ export class Connection extends TypedEventEmitter<ConnectionEvents> {
   public authContext?: AuthContext;
   public delayedTimeoutId: NodeJS.Timeout | null = null;
   public generation: number;
+  public accessToken?: string;
   public readonly description: Readonly<StreamDescription>;
   /**
    * Represents if the connection has been established:

package/src/cmap/connection_pool.ts

@@ -551,7 +551,8 @@ export class ConnectionPool extends TypedEventEmitter<ConnectionPoolEvents> {
 
     const resolvedCredentials = credentials.resolveAuthMechanism(connection.hello);
     const provider = this[kServer].topology.client.s.authProviders.getOrCreateProvider(
-      resolvedCredentials.mechanism
+      resolvedCredentials.mechanism,
+      resolvedCredentials.mechanismProperties
     );
 
     if (!provider) {

package/src/connection_string.ts

@@ -698,6 +698,9 @@ export const OPTIONS = {
       });
     }
   },
+  // Note that if the authMechanismProperties contain a TOKEN_RESOURCE that has a
+  // comma in it, it MUST be supplied as a MongoClient option instead of in the
+  // connection string.
   authMechanismProperties: {
     target: 'credentials',
     transform({ options, values }): MongoCredentials {

package/src/error.ts

@@ -36,6 +36,7 @@ export const NODE_IS_RECOVERING_ERROR_MESSAGE = new RegExp('node is recovering',
 export const MONGODB_ERROR_CODES = Object.freeze({
   HostUnreachable: 6,
   HostNotFound: 7,
+  AuthenticationFailed: 18,
   NetworkTimeout: 89,
   ShutdownInProgress: 91,
   PrimarySteppedDown: 189,
@@ -529,6 +530,34 @@ export class MongoAWSError extends MongoRuntimeError {
   }
 }
 
+/**
+ * A error generated when the user attempts to authenticate
+ * via OIDC callbacks, but fails.
+ *
+ * @public
+ * @category Error
+ */
+export class MongoOIDCError extends MongoRuntimeError {
+  /**
+   * **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(): string {
+    return 'MongoOIDCError';
+  }
+}
+
 /**
  * A error generated when the user attempts to authenticate
  * via Azure, but fails.
@@ -536,7 +565,7 @@ export class MongoAWSError extends MongoRuntimeError {
  * @public
  * @category Error
  */
-export class MongoAzureError extends MongoRuntimeError {
+export class MongoAzureError extends MongoOIDCError {
   /**
    * **Do not use this constructor!**
    *
@@ -557,6 +586,34 @@ export class MongoAzureError extends MongoRuntimeError {
   }
 }
 
+/**
+ * A error generated when the user attempts to authenticate
+ * via GCP, but fails.
+ *
+ * @public
+ * @category Error
+ */
+export class MongoGCPError extends MongoOIDCError {
+  /**
+   * **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(): string {
+    return 'MongoGCPError';
+  }
+}
+
 /**
  * An error generated when a ChangeStream operation fails to execute.
  *

package/src/index.ts

@@ -52,6 +52,7 @@ export {
   MongoDriverError,
   MongoError,
   MongoExpiredSessionError,
+  MongoGCPError,
   MongoGridFSChunkError,
   MongoGridFSStreamError,
   MongoInvalidArgumentError,
@@ -61,6 +62,7 @@ export {
   MongoNetworkError,
   MongoNetworkTimeoutError,
   MongoNotConnectedError,
+  MongoOIDCError,
   MongoParseError,
   MongoRuntimeError,
   MongoServerClosedError,
@@ -250,12 +252,14 @@ export type {
   MongoCredentialsOptions
 } from './cmap/auth/mongo_credentials';
 export type {
-  IdPServerInfo,
+  IdPInfo,
   IdPServerResponse,
-  OIDCCallbackContext,
-  OIDCRefreshFunction,
-  OIDCRequestFunction
+  OIDCCallbackFunction,
+  OIDCCallbackParams,
+  OIDCResponse
 } from './cmap/auth/mongodb_oidc';
+export type { Workflow } from './cmap/auth/mongodb_oidc';
+export type { TokenCache } from './cmap/auth/mongodb_oidc/token_cache';
 export type {
   MessageHeader,
   OpCompressedRequest,

package/src/mongo_client.ts

@@ -10,6 +10,7 @@ import {
   DEFAULT_ALLOWED_HOSTS,
   type MongoCredentials
 } from './cmap/auth/mongo_credentials';
+import { type TokenCache } from './cmap/auth/mongodb_oidc/token_cache';
 import { AuthMechanism } from './cmap/auth/providers';
 import type { LEGAL_TCP_SOCKET_OPTIONS, LEGAL_TLS_SOCKET_OPTIONS } from './cmap/connect';
 import type { Connection } from './cmap/connection';
@@ -524,7 +525,7 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> {
     if (options.credentials?.mechanism === AuthMechanism.MONGODB_OIDC) {
       const allowedHosts =
         options.credentials?.mechanismProperties?.ALLOWED_HOSTS || DEFAULT_ALLOWED_HOSTS;
-      const isServiceAuth = !!options.credentials?.mechanismProperties?.PROVIDER_NAME;
+      const isServiceAuth = !!options.credentials?.mechanismProperties?.ENVIRONMENT;
       if (!isServiceAuth) {
         for (const host of options.hosts) {
           if (!hostMatchesWildcards(host.toHostPort().host, allowedHosts)) {
@@ -828,6 +829,8 @@ export interface MongoOptions
   extendedMetadata: Promise<Document>;
   /** @internal */
   autoEncrypter?: AutoEncrypter;
+  /** @internal */
+  tokenCache?: TokenCache;
   proxyHost?: string;
   proxyPort?: number;
   proxyUsername?: string;