@depup/mongodb 7.1.0-depup.0

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

@@ -0,0 +1,188 @@
+import { setTimeout } from 'timers/promises';
+
+import { type Document } from '../../../bson';
+import { MongoMissingCredentialsError } from '../../../error';
+import { ns } from '../../../utils';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import {
+  type OIDCCallbackFunction,
+  type OIDCCallbackParams,
+  type OIDCResponse,
+  type Workflow
+} from '../mongodb_oidc';
+import { finishCommandDocument, startCommandDocument } from './command_builders';
+import { type TokenCache } from './token_cache';
+
+/** 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'];
+
+/** Error message when the callback result is invalid. */
+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 abstract class CallbackWorkflow implements Workflow {
+  cache: TokenCache;
+  callback: OIDCCallbackFunction;
+  lastExecutionTime: number;
+
+  /**
+   * Instantiate the callback workflow.
+   */
+  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(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 {};
+  }
+
+  /**
+   * 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 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);
+  }
+
+  /**
+   * 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.
+   */
+  protected async startAuthentication(
+    connection: Connection,
+    credentials: MongoCredentials,
+    response?: Document
+  ): Promise<Document> {
+    let result;
+    if (response?.speculativeAuthenticate) {
+      result = response.speculativeAuthenticate;
+    } else {
+      result = await connection.command(
+        ns(credentials.source),
+        startCommandDocument(credentials),
+        undefined
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Finishes the callback authentication process.
+   */
+  protected async finishAuthentication(
+    connection: Connection,
+    credentials: MongoCredentials,
+    token: string,
+    conversationId?: number
+  ): Promise<void> {
+    await connection.command(
+      ns(credentials.source),
+      finishCommandDocument(token, conversationId),
+      undefined
+    );
+  }
+
+  /**
+   * Executes the callback and validates the output.
+   */
+  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)) {
+      throw new MongoMissingCredentialsError(CALLBACK_RESULT_ERROR);
+    }
+    return result;
+  }
+
+  /**
+   * 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
+
+        .catch(() => null)
+
+        .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;
+    };
+  }
+}
+
+/**
+ * Determines if a result returned from a request or refresh callback
+ * function is invalid. This means the result is nullish, doesn't contain
+ * the accessToken required field, and does not contain extra fields.
+ */
+function isCallbackResultInvalid(tokenResult: unknown): boolean {
+  if (tokenResult == null || typeof tokenResult !== 'object') return true;
+  if (!('accessToken' in tokenResult)) return true;
+  return !Object.getOwnPropertyNames(tokenResult).every(prop => RESULT_PROPERTIES.includes(prop));
+}

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

@@ -0,0 +1,53 @@
+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,46 @@
+import { MongoGCPError } from '../../../error';
+import { get } from '../../../utils';
+import type { OIDCCallbackFunction, OIDCCallbackParams, OIDCResponse } from '../mongodb_oidc';
+
+/** 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.';
+
+/**
+ * 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;
+  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<OIDCResponse> {
+  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 { accessToken: response.body };
+}

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

@@ -0,0 +1,141 @@
+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();
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+import { readFile } from 'fs/promises';
+import * as process from 'process';
+
+import type { OIDCCallbackFunction, OIDCResponse } from '../mongodb_oidc';
+
+/** The fallback file name */
+const FALLBACK_FILENAME = '/var/run/secrets/kubernetes.io/serviceaccount/token';
+
+/** The azure environment variable for the file name. */
+const AZURE_FILENAME = 'AZURE_FEDERATED_TOKEN_FILE';
+
+/** The AWS environment variable for the file name. */
+const AWS_FILENAME = 'AWS_WEB_IDENTITY_TOKEN_FILE';
+
+/**
+ * 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 (): Promise<OIDCResponse> => {
+  let filename: string;
+  if (process.env[AZURE_FILENAME]) {
+    filename = process.env[AZURE_FILENAME];
+  } else if (process.env[AWS_FILENAME]) {
+    filename = process.env[AWS_FILENAME];
+  } else {
+    filename = FALLBACK_FILENAME;
+  }
+  const token = await readFile(filename, 'utf8');
+  return { accessToken: token };
+};

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,22 @@
+import * as fs from 'fs';
+import * as process from 'process';
+
+import { MongoAWSError } from '../../../error';
+import type { OIDCCallbackFunction, OIDCResponse } from '../mongodb_oidc';
+
+/** Error for when the token is missing in the environment. */
+const TOKEN_MISSING_ERROR = 'OIDC_TOKEN_FILE must be set in the environment.';
+
+/**
+ * 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 (): Promise<OIDCResponse> => {
+  const tokenFile = process.env.OIDC_TOKEN_FILE;
+  if (!tokenFile) {
+    throw new MongoAWSError(TOKEN_MISSING_ERROR);
+  }
+  const token = await fs.promises.readFile(tokenFile, 'utf8');
+  return { accessToken: token };
+};