mongodb 6.6.2 → 6.7.0

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

@@ -1,26 +1,23 @@
-import { Binary, BSON, type Document } from 'bson';
+import { type Document } from 'bson';
+import { setTimeout } from 'timers/promises';
 
-import { MONGODB_ERROR_CODES, MongoError, MongoMissingCredentialsError } from '../../../error';
+import { MongoMissingCredentialsError } from '../../../error';
 import { ns } from '../../../utils';
 import type { Connection } from '../../connection';
 import type { MongoCredentials } from '../mongo_credentials';
-import type {
-  IdPServerInfo,
-  IdPServerResponse,
-  OIDCCallbackContext,
-  OIDCRefreshFunction,
-  OIDCRequestFunction,
-  Workflow
+import {
+  type OIDCCallbackFunction,
+  type OIDCCallbackParams,
+  type OIDCResponse,
+  type Workflow
 } from '../mongodb_oidc';
-import { AuthMechanism } from '../providers';
-import { CallbackLockCache } from './callback_lock_cache';
-import { TokenEntryCache } from './token_entry_cache';
+import { finishCommandDocument, startCommandDocument } from './command_builders';
+import { type TokenCache } from './token_cache';
 
-/** The current version of OIDC implementation. */
-const OIDC_VERSION = 0;
-
-/** 5 minutes in seconds */
-const TIMEOUT_S = 300;
+/** 5 minutes in milliseconds */
+export const HUMAN_TIMEOUT_MS = 300000;
+/** 1 minute in milliseconds */
+export const AUTOMATED_TIMEOUT_MS = 60000;
 
 /** Properties allowed on results of callbacks. */
 const RESULT_PROPERTIES = ['accessToken', 'expiresInSeconds', 'refreshToken'];
@@ -29,138 +26,89 @@ const RESULT_PROPERTIES = ['accessToken', 'expiresInSeconds', 'refreshToken'];
 const CALLBACK_RESULT_ERROR =
   'User provided OIDC callbacks must return a valid object with an accessToken.';
 
+/** The time to throttle callback calls. */
+const THROTTLE_MS = 100;
+
 /**
  * OIDC implementation of a callback based workflow.
  * @internal
  */
-export class CallbackWorkflow implements Workflow {
-  cache: TokenEntryCache;
-  callbackCache: CallbackLockCache;
+export abstract class CallbackWorkflow implements Workflow {
+  cache: TokenCache;
+  callback: OIDCCallbackFunction;
+  lastExecutionTime: number;
 
   /**
-   * Instantiate the workflow
+   * Instantiate the callback workflow.
    */
-  constructor() {
-    this.cache = new TokenEntryCache();
-    this.callbackCache = new CallbackLockCache();
+  constructor(cache: TokenCache, callback: OIDCCallbackFunction) {
+    this.cache = cache;
+    this.callback = this.withLock(callback);
+    this.lastExecutionTime = Date.now() - THROTTLE_MS;
   }
 
   /**
    * Get the document to add for speculative authentication. This also needs
    * to add a db field from the credentials source.
    */
-  async speculativeAuth(credentials: MongoCredentials): Promise<Document> {
-    const document = startCommandDocument(credentials);
-    document.db = credentials.source;
-    return { speculativeAuthenticate: document };
+  async speculativeAuth(connection: Connection, credentials: MongoCredentials): Promise<Document> {
+    // Check if the Client Cache has an access token.
+    // If it does, cache the access token in the Connection Cache and send a JwtStepRequest
+    // with the cached access token in the speculative authentication SASL payload.
+    if (this.cache.hasAccessToken) {
+      const accessToken = this.cache.getAccessToken();
+      connection.accessToken = accessToken;
+      const document = finishCommandDocument(accessToken);
+      document.db = credentials.source;
+      return { speculativeAuthenticate: document };
+    }
+    return {};
   }
 
   /**
-   * Execute the OIDC callback workflow.
+   * Reauthenticate the callback workflow. For this we invalidated the access token
+   * in the cache and run the authentication steps again. No initial handshake needs
+   * to be sent.
    */
-  async execute(
-    connection: Connection,
-    credentials: MongoCredentials,
-    reauthenticating: boolean,
-    response?: Document
-  ): Promise<Document> {
-    // Get the callbacks with locks from the callback lock cache.
-    const { requestCallback, refreshCallback, callbackHash } = this.callbackCache.getEntry(
-      connection,
-      credentials
-    );
-    // Look for an existing entry in the cache.
-    const entry = this.cache.getEntry(connection.address, credentials.username, callbackHash);
-    let result;
-    if (entry) {
-      // Reauthentication cannot use a token from the cache since the server has
-      // stated it is invalid by the request for reauthentication.
-      if (entry.isValid() && !reauthenticating) {
-        // Presence of a valid cache entry means we can skip to the finishing step.
-        result = await this.finishAuthentication(
-          connection,
-          credentials,
-          entry.tokenResult,
-          response?.speculativeAuthenticate?.conversationId
-        );
+  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 {
-        // Presence of an expired cache entry means we must fetch a new one and
-        // then execute the final step.
-        const tokenResult = await this.fetchAccessToken(
-          connection,
-          credentials,
-          entry.serverInfo,
-          reauthenticating,
-          callbackHash,
-          requestCallback,
-          refreshCallback
-        );
-        try {
-          result = await this.finishAuthentication(
-            connection,
-            credentials,
-            tokenResult,
-            reauthenticating ? undefined : response?.speculativeAuthenticate?.conversationId
-          );
-        } catch (error) {
-          // If we are reauthenticating and this errors with reauthentication
-          // required, we need to do the entire process over again and clear
-          // the cache entry.
-          if (
-            reauthenticating &&
-            error instanceof MongoError &&
-            error.code === MONGODB_ERROR_CODES.Reauthenticate
-          ) {
-            this.cache.deleteEntry(connection.address, credentials.username, callbackHash);
-            result = await this.execute(connection, credentials, reauthenticating);
-          } else {
-            throw error;
-          }
-        }
+        // 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();
       }
-    } else {
-      // No entry in the cache requires us to do all authentication steps
-      // from start to finish, including getting a fresh token for the cache.
-      const startDocument = await this.startAuthentication(
-        connection,
-        credentials,
-        reauthenticating,
-        response
-      );
-      const conversationId = startDocument.conversationId;
-      const serverResult = BSON.deserialize(startDocument.payload.buffer) as IdPServerInfo;
-      const tokenResult = await this.fetchAccessToken(
-        connection,
-        credentials,
-        serverResult,
-        reauthenticating,
-        callbackHash,
-        requestCallback,
-        refreshCallback
-      );
-      result = await this.finishAuthentication(
-        connection,
-        credentials,
-        tokenResult,
-        conversationId
-      );
     }
-    return result;
+    await this.execute(connection, credentials);
   }
 
+  /**
+   * Execute the OIDC callback workflow.
+   */
+  abstract execute(
+    connection: Connection,
+    credentials: MongoCredentials,
+    response?: Document
+  ): Promise<void>;
+
   /**
    * Starts the callback authentication process. If there is a speculative
    * authentication document from the initial handshake, then we will use that
    * value to get the issuer, otherwise we will send the saslStart command.
    */
-  private async startAuthentication(
+  protected async startAuthentication(
     connection: Connection,
     credentials: MongoCredentials,
-    reauthenticating: boolean,
     response?: Document
   ): Promise<Document> {
     let result;
-    if (!reauthenticating && response?.speculativeAuthenticate) {
+    if (response?.speculativeAuthenticate) {
       result = response.speculativeAuthenticate;
     } else {
       result = await connection.command(
@@ -175,97 +123,57 @@ export class CallbackWorkflow implements Workflow {
   /**
    * Finishes the callback authentication process.
    */
-  private async finishAuthentication(
+  protected async finishAuthentication(
     connection: Connection,
     credentials: MongoCredentials,
-    tokenResult: IdPServerResponse,
+    token: string,
     conversationId?: number
-  ): Promise<Document> {
-    const result = await connection.command(
+  ): Promise<void> {
+    await connection.command(
       ns(credentials.source),
-      finishCommandDocument(tokenResult.accessToken, conversationId),
+      finishCommandDocument(token, conversationId),
       undefined
     );
-    return result;
   }
 
   /**
-   * Fetches an access token using either the request or refresh callbacks and
-   * puts it in the cache.
+   * Executes the callback and validates the output.
    */
-  private async fetchAccessToken(
-    connection: Connection,
-    credentials: MongoCredentials,
-    serverInfo: IdPServerInfo,
-    reauthenticating: boolean,
-    callbackHash: string,
-    requestCallback: OIDCRequestFunction,
-    refreshCallback?: OIDCRefreshFunction
-  ): Promise<IdPServerResponse> {
-    // Get the token from the cache.
-    const entry = this.cache.getEntry(connection.address, credentials.username, callbackHash);
-    let result;
-    const context: OIDCCallbackContext = { timeoutSeconds: TIMEOUT_S, version: OIDC_VERSION };
-    // Check if there's a token in the cache.
-    if (entry) {
-      // If the cache entry is valid, return the token result.
-      if (entry.isValid() && !reauthenticating) {
-        return entry.tokenResult;
-      }
-      // If the cache entry is not valid, remove it from the cache and first attempt
-      // to use the refresh callback to get a new token. If no refresh callback
-      // exists, then fallback to the request callback.
-      if (refreshCallback) {
-        context.refreshToken = entry.tokenResult.refreshToken;
-        result = await refreshCallback(serverInfo, context);
-      } else {
-        result = await requestCallback(serverInfo, context);
-      }
-    } else {
-      // With no token in the cache we use the request callback.
-      result = await requestCallback(serverInfo, context);
-    }
+  protected async executeAndValidateCallback(params: OIDCCallbackParams): Promise<OIDCResponse> {
+    const result = await this.callback(params);
     // Validate that the result returned by the callback is acceptable. If it is not
     // we must clear the token result from the cache.
     if (isCallbackResultInvalid(result)) {
-      this.cache.deleteEntry(connection.address, credentials.username, callbackHash);
       throw new MongoMissingCredentialsError(CALLBACK_RESULT_ERROR);
     }
-    // Cleanup the cache.
-    this.cache.deleteExpiredEntries();
-    // Put the new entry into the cache.
-    this.cache.addEntry(
-      connection.address,
-      credentials.username || '',
-      callbackHash,
-      result,
-      serverInfo
-    );
     return result;
   }
-}
 
-/**
- * Generate the finishing command document for authentication. Will be a
- * saslStart or saslContinue depending on the presence of a conversation id.
- */
-function finishCommandDocument(token: string, conversationId?: number): Document {
-  if (conversationId != null && typeof conversationId === 'number') {
-    return {
-      saslContinue: 1,
-      conversationId: conversationId,
-      payload: new Binary(BSON.serialize({ jwt: token }))
+  /**
+   * Ensure the callback is only executed one at a time and throttles the calls
+   * to every 100ms.
+   */
+  protected withLock(callback: OIDCCallbackFunction): OIDCCallbackFunction {
+    let lock: Promise<any> = Promise.resolve();
+    return async (params: OIDCCallbackParams): Promise<OIDCResponse> => {
+      // 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, { signal: params.timeoutContext });
+          }
+          this.lastExecutionTime = Date.now();
+          return await callback(params);
+        });
+      return await lock;
     };
   }
-  // saslContinue requires a conversationId in the command to be valid so in this
-  // case the server allows "step two" to actually be a saslStart with the token
-  // as the jwt since the use of the cached value has no correlating conversating
-  // on the particular connection.
-  return {
-    saslStart: 1,
-    mechanism: AuthMechanism.MONGODB_OIDC,
-    payload: new Binary(BSON.serialize({ jwt: token }))
-  };
 }
 
 /**
@@ -278,19 +186,3 @@ function isCallbackResultInvalid(tokenResult: unknown): boolean {
   if (!('accessToken' in tokenResult)) return true;
   return !Object.getOwnPropertyNames(tokenResult).every(prop => RESULT_PROPERTIES.includes(prop));
 }
-
-/**
- * Generate the saslStart command document.
- */
-function startCommandDocument(credentials: MongoCredentials): Document {
-  const payload: Document = {};
-  if (credentials.username) {
-    payload.n = credentials.username;
-  }
-  return {
-    saslStart: 1,
-    autoAuthorize: 1,
-    mechanism: AuthMechanism.MONGODB_OIDC,
-    payload: new Binary(BSON.serialize(payload))
-  };
-}

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

@@ -0,0 +1,54 @@
+import { Binary, BSON, type Document } from 'bson';
+
+import { type MongoCredentials } from '../mongo_credentials';
+import { AuthMechanism } from '../providers';
+
+/** @internal */
+export interface OIDCCommand {
+  saslStart?: number;
+  saslContinue?: number;
+  conversationId?: number;
+  mechanism?: string;
+  autoAuthorize?: number;
+  db?: string;
+  payload: Binary;
+}
+
+/**
+ * Generate the finishing command document for authentication. Will be a
+ * saslStart or saslContinue depending on the presence of a conversation id.
+ */
+export function finishCommandDocument(token: string, conversationId?: number): OIDCCommand {
+  if (conversationId != null) {
+    return {
+      saslContinue: 1,
+      conversationId: conversationId,
+      payload: new Binary(BSON.serialize({ jwt: token }))
+    };
+  }
+  // saslContinue requires a conversationId in the command to be valid so in this
+  // case the server allows "step two" to actually be a saslStart with the token
+  // as the jwt since the use of the cached value has no correlating conversating
+  // on the particular connection.
+  return {
+    saslStart: 1,
+    mechanism: AuthMechanism.MONGODB_OIDC,
+    payload: new Binary(BSON.serialize({ jwt: token }))
+  };
+}
+
+/**
+ * Generate the saslStart command document.
+ */
+export function startCommandDocument(credentials: MongoCredentials): OIDCCommand {
+  const payload: Document = {};
+  if (credentials.username) {
+    payload.n = credentials.username;
+  }
+  return {
+    saslStart: 1,
+    autoAuthorize: 1,
+    mechanism: AuthMechanism.MONGODB_OIDC,
+    payload: new Binary(BSON.serialize(payload))
+  };
+}

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

@@ -0,0 +1,53 @@
+import { MongoGCPError } from '../../../error';
+import { get } from '../../../utils';
+import { type MongoCredentials } from '../mongo_credentials';
+import { type AccessToken, MachineWorkflow } from './machine_workflow';
+import { type TokenCache } from './token_cache';
+
+/** GCP base URL. */
+const GCP_BASE_URL =
+  'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity';
+
+/** GCP request headers. */
+const GCP_HEADERS = Object.freeze({ 'Metadata-Flavor': 'Google' });
+
+/** 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 gcp.';
+
+export class GCPMachineWorkflow extends MachineWorkflow {
+  /**
+   * Instantiate the machine workflow.
+   */
+  constructor(cache: TokenCache) {
+    super(cache);
+  }
+
+  /**
+   * Get the token from the environment.
+   */
+  async getToken(credentials?: MongoCredentials): Promise<AccessToken> {
+    const tokenAudience = credentials?.mechanismProperties.TOKEN_RESOURCE;
+    if (!tokenAudience) {
+      throw new MongoGCPError(TOKEN_RESOURCE_MISSING_ERROR);
+    }
+    return await getGcpTokenData(tokenAudience);
+  }
+}
+
+/**
+ * Hit the GCP endpoint to get the token data.
+ */
+async function getGcpTokenData(tokenAudience: string): Promise<AccessToken> {
+  const url = new URL(GCP_BASE_URL);
+  url.searchParams.append('audience', tokenAudience);
+  const response = await get(url, {
+    headers: GCP_HEADERS
+  });
+  if (response.status !== 200) {
+    throw new MongoGCPError(
+      `Status code ${response.status} returned from the GCP endpoint. Response body: ${response.body}`
+    );
+  }
+  return { access_token: response.body };
+}

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

@@ -0,0 +1,142 @@
+import { BSON } from 'bson';
+
+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 {
+  type IdPInfo,
+  OIDC_VERSION,
+  type OIDCCallbackFunction,
+  type OIDCCallbackParams,
+  type OIDCResponse
+} from '../mongodb_oidc';
+import { CallbackWorkflow, HUMAN_TIMEOUT_MS } from './callback_workflow';
+import { type TokenCache } from './token_cache';
+
+/**
+ * Class implementing behaviour for the non human callback workflow.
+ * @internal
+ */
+export class HumanCallbackWorkflow extends CallbackWorkflow {
+  /**
+   * Instantiate the human callback workflow.
+   */
+  constructor(cache: TokenCache, callback: OIDCCallbackFunction) {
+    super(cache, callback);
+  }
+
+  /**
+   * Execute the OIDC human callback workflow.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<void> {
+    // Check if the Client Cache has an access token.
+    // If it does, cache the access token in the Connection Cache and perform a One-Step SASL conversation
+    // using the access token. If the server returns an Authentication error (18),
+    // invalidate the access token token from the Client Cache, clear the Connection Cache,
+    // and restart the authentication flow. Raise any other errors to the user. On success, exit the algorithm.
+    if (this.cache.hasAccessToken) {
+      const token = this.cache.getAccessToken();
+      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();
+          delete connection.accessToken;
+          return await this.execute(connection, credentials);
+        } else {
+          throw error;
+        }
+      }
+    }
+    // Check if the Client Cache has a refresh token.
+    // If it does, call the OIDC Human Callback with the cached refresh token and IdpInfo to get a
+    // new access token. Cache the new access token in the Client Cache and Connection Cache.
+    // Perform a One-Step SASL conversation using the new access token. If the the server returns
+    // an Authentication error (18), clear the refresh token, invalidate the access token from the
+    // Client Cache, clear the Connection Cache, and restart the authentication flow. Raise any other
+    // errors to the user. On success, exit the algorithm.
+    if (this.cache.hasRefreshToken) {
+      const refreshToken = this.cache.getRefreshToken();
+      const result = await this.fetchAccessToken(
+        this.cache.getIdpInfo(),
+        credentials,
+        refreshToken
+      );
+      this.cache.put(result);
+      connection.accessToken = result.accessToken;
+      try {
+        return await this.finishAuthentication(connection, credentials, result.accessToken);
+      } catch (error) {
+        if (
+          error instanceof MongoError &&
+          error.code === MONGODB_ERROR_CODES.AuthenticationFailed
+        ) {
+          this.cache.removeRefreshToken();
+          delete connection.accessToken;
+          return await this.execute(connection, credentials);
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    // Start a new Two-Step SASL conversation.
+    // Run a PrincipalStepRequest to get the IdpInfo.
+    // Call the OIDC Human Callback with the new IdpInfo to get a new access token and optional refresh
+    // token. Drivers MUST NOT pass a cached refresh token to the callback when performing
+    // a new Two-Step conversation. Cache the new IdpInfo and refresh token in the Client Cache and the
+    // new access token in the Client Cache and Connection Cache.
+    // Attempt to authenticate using a JwtStepRequest with the new access token. Raise any errors to the user.
+    const startResponse = await this.startAuthentication(connection, credentials);
+    const conversationId = startResponse.conversationId;
+    const idpInfo = BSON.deserialize(startResponse.payload.buffer) as IdPInfo;
+    const callbackResponse = await this.fetchAccessToken(idpInfo, credentials);
+    this.cache.put(callbackResponse, idpInfo);
+    connection.accessToken = callbackResponse.accessToken;
+    return await this.finishAuthentication(
+      connection,
+      credentials,
+      callbackResponse.accessToken,
+      conversationId
+    );
+  }
+
+  /**
+   * Fetches an access token using the callback.
+   */
+  private async fetchAccessToken(
+    idpInfo: IdPInfo,
+    credentials: MongoCredentials,
+    refreshToken?: string
+  ): Promise<OIDCResponse> {
+    const controller = new AbortController();
+    const params: OIDCCallbackParams = {
+      timeoutContext: controller.signal,
+      version: OIDC_VERSION,
+      idpInfo: idpInfo
+    };
+    if (credentials.username) {
+      params.username = credentials.username;
+    }
+    if (refreshToken) {
+      params.refreshToken = refreshToken;
+    }
+    const timeout = Timeout.expires(HUMAN_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 ${HUMAN_TIMEOUT_MS}ms.`);
+      }
+      throw error;
+    } finally {
+      timeout.clear();
+    }
+  }
+}