mongodb 5.1.0 → 5.3.0

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

@@ -0,0 +1,259 @@
+import { Binary, BSON, type Document } from 'bson';
+
+import { MongoInvalidArgumentError, MongoMissingCredentialsError } from '../../../error';
+import { ns } from '../../../utils';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import type { OIDCMechanismServerStep1, OIDCRequestTokenResult } from '../mongodb_oidc';
+import { AuthMechanism } from '../providers';
+import { TokenEntryCache } from './token_entry_cache';
+import type { Workflow } from './workflow';
+
+/* 5 minutes in milliseconds */
+const TIMEOUT_MS = 300000;
+
+/**
+ * OIDC implementation of a callback based workflow.
+ * @internal
+ */
+export class CallbackWorkflow implements Workflow {
+  cache: TokenEntryCache;
+
+  /**
+   * Instantiate the workflow
+   */
+  constructor() {
+    this.cache = new TokenEntryCache();
+  }
+
+  /**
+   * Get the document to add for speculative authentication. Is empty when
+   * callbacks are in play.
+   */
+  speculativeAuth(): Promise<Document> {
+    return Promise.resolve({});
+  }
+
+  /**
+   * Execute the workflow.
+   *
+   * Steps:
+   * - If an entry is in the cache
+   *   - If it is not expired
+   *     - Skip step one and use the entry to execute step two.
+   *   - If it is expired
+   *     - If the refresh callback exists
+   *       - remove expired entry from cache
+   *       - call the refresh callback.
+   *       - put the new entry in the cache.
+   *       - execute step two.
+   *     - If the refresh callback does not exist.
+   *       - remove expired entry from cache
+   *       - call the request callback.
+   *       - put the new entry in the cache.
+   *       - execute step two.
+   * - If no entry is in the cache.
+   *   - execute step one.
+   *   - call the refresh callback.
+   *   - put the new entry in the cache.
+   *   - execute step two.
+   */
+  async execute(
+    connection: Connection,
+    credentials: MongoCredentials,
+    reauthenticate = false
+  ): Promise<Document> {
+    const request = credentials.mechanismProperties.REQUEST_TOKEN_CALLBACK;
+    const refresh = credentials.mechanismProperties.REFRESH_TOKEN_CALLBACK;
+
+    const entry = this.cache.getEntry(
+      connection.address,
+      credentials.username,
+      request || null,
+      refresh || null
+    );
+    if (entry) {
+      // Check if the entry is not expired and if we are reauthenticating.
+      if (!reauthenticate && entry.isValid()) {
+        // Skip step one and execute the step two saslContinue.
+        try {
+          const result = await finishAuth(entry.tokenResult, undefined, connection, credentials);
+          return result;
+        } catch (error) {
+          // If authentication errors when using a cached token we remove it from
+          // the cache.
+          this.cache.deleteEntry(
+            connection.address,
+            credentials.username || '',
+            request || null,
+            refresh || null
+          );
+          throw error;
+        }
+      } else {
+        // Remove the expired entry from the cache.
+        this.cache.deleteEntry(
+          connection.address,
+          credentials.username || '',
+          request || null,
+          refresh || null
+        );
+        // Execute a refresh of the token and finish auth.
+        return this.refreshAndFinish(
+          connection,
+          credentials,
+          entry.serverResult,
+          entry.tokenResult
+        );
+      }
+    } else {
+      // No entry means to start with the step one saslStart.
+      const result = await connection.commandAsync(
+        ns(credentials.source),
+        startCommandDocument(credentials),
+        undefined
+      );
+      const stepOne = BSON.deserialize(result.payload.buffer) as OIDCMechanismServerStep1;
+      // Call the request callback and finish auth.
+      return this.requestAndFinish(connection, credentials, stepOne, result.conversationId);
+    }
+  }
+
+  /**
+   * Execute the refresh callback if it exists, otherwise the request callback, then
+   * finish the authentication.
+   */
+  private async refreshAndFinish(
+    connection: Connection,
+    credentials: MongoCredentials,
+    stepOneResult: OIDCMechanismServerStep1,
+    tokenResult: OIDCRequestTokenResult,
+    conversationId?: number
+  ): Promise<Document> {
+    const request = credentials.mechanismProperties.REQUEST_TOKEN_CALLBACK;
+    const refresh = credentials.mechanismProperties.REFRESH_TOKEN_CALLBACK;
+    // If a refresh callback exists, use it. Otherwise use the request callback.
+    if (refresh) {
+      const result: OIDCRequestTokenResult = await refresh(
+        credentials.username,
+        stepOneResult,
+        tokenResult,
+        TIMEOUT_MS
+      );
+      // Validate the result.
+      if (!result || !result.accessToken) {
+        throw new MongoMissingCredentialsError(
+          'REFRESH_TOKEN_CALLBACK must return a valid object with an accessToken'
+        );
+      }
+      // Cache a new entry and continue with the saslContinue.
+      this.cache.addEntry(
+        connection.address,
+        credentials.username || '',
+        request || null,
+        refresh,
+        result,
+        stepOneResult
+      );
+      return finishAuth(result, conversationId, connection, credentials);
+    } else {
+      // Fallback to using the request callback.
+      return this.requestAndFinish(connection, credentials, stepOneResult, conversationId);
+    }
+  }
+
+  /**
+   * Execute the request callback and finish authentication.
+   */
+  private async requestAndFinish(
+    connection: Connection,
+    credentials: MongoCredentials,
+    stepOneResult: OIDCMechanismServerStep1,
+    conversationId?: number
+  ): Promise<Document> {
+    // Call the request callback.
+    const request = credentials.mechanismProperties.REQUEST_TOKEN_CALLBACK;
+    const refresh = credentials.mechanismProperties.REFRESH_TOKEN_CALLBACK;
+    // Always clear expired entries from the cache on each finish as cleanup.
+    this.cache.deleteExpiredEntries();
+    if (!request) {
+      // Request callback must be present.
+      throw new MongoInvalidArgumentError(
+        'Auth mechanism property REQUEST_TOKEN_CALLBACK is required.'
+      );
+    }
+    const tokenResult = await request(credentials.username, stepOneResult, TIMEOUT_MS);
+    // Validate the result.
+    if (!tokenResult || !tokenResult.accessToken) {
+      throw new MongoMissingCredentialsError(
+        'REQUEST_TOKEN_CALLBACK must return a valid object with an accessToken'
+      );
+    }
+    // Cache a new entry and continue with the saslContinue.
+    this.cache.addEntry(
+      connection.address,
+      credentials.username || '',
+      request,
+      refresh || null,
+      tokenResult,
+      stepOneResult
+    );
+    return finishAuth(tokenResult, conversationId, connection, credentials);
+  }
+}
+
+/**
+ * Cache the result of the user supplied callback and execute the
+ * step two saslContinue.
+ */
+async function finishAuth(
+  result: OIDCRequestTokenResult,
+  conversationId: number | undefined,
+  connection: Connection,
+  credentials: MongoCredentials
+): Promise<Document> {
+  // Execute the step two saslContinue.
+  return connection.commandAsync(
+    ns(credentials.source),
+    continueCommandDocument(result.accessToken, conversationId),
+    undefined
+  );
+}
+
+/**
+ * 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))
+  };
+}
+
+/**
+ * Generate the saslContinue command document.
+ */
+function continueCommandDocument(token: string, conversationId?: number): Document {
+  if (conversationId) {
+    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 }))
+  };
+}

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

@@ -0,0 +1,47 @@
+import { BSON, type Document } from 'bson';
+
+import { ns } from '../../../utils';
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+import { AuthMechanism } from '../providers';
+import type { Workflow } from './workflow';
+
+/**
+ * Common behaviour for OIDC device workflows.
+ * @internal
+ */
+export abstract class ServiceWorkflow implements Workflow {
+  /**
+   * Execute the workflow. Looks for AWS_WEB_IDENTITY_TOKEN_FILE in the environment
+   * and then attempts to read the token from that path.
+   */
+  async execute(connection: Connection, credentials: MongoCredentials): Promise<Document> {
+    const token = await this.getToken();
+    const command = commandDocument(token);
+    return connection.commandAsync(ns(credentials.source), command, undefined);
+  }
+
+  /**
+   * Get the document to add for speculative authentication.
+   */
+  async speculativeAuth(): Promise<Document> {
+    const token = await this.getToken();
+    return { speculativeAuthenticate: commandDocument(token) };
+  }
+
+  /**
+   * Get the token from the environment or endpoint.
+   */
+  abstract getToken(): Promise<string>;
+}
+
+/**
+ * Create the saslStart command document.
+ */
+export function commandDocument(token: string): Document {
+  return {
+    saslStart: 1,
+    mechanism: AuthMechanism.MONGODB_OIDC,
+    payload: BSON.serialize({ jwt: token })
+  };
+}

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

@@ -0,0 +1,166 @@
+import type {
+  OIDCMechanismServerStep1,
+  OIDCRefreshFunction,
+  OIDCRequestFunction,
+  OIDCRequestTokenResult
+} from '../mongodb_oidc';
+
+/* 5 minutes in milliseonds */
+const EXPIRATION_BUFFER_MS = 300000;
+/* Default expiration is now for when no expiration provided */
+const DEFAULT_EXPIRATION_SECS = 0;
+/* Counter for function "hashes".*/
+let FN_HASH_COUNTER = 0;
+/* No function present function */
+const NO_FUNCTION: OIDCRequestFunction = () => {
+  return Promise.resolve({ accessToken: 'test' });
+};
+/* The map of function hashes */
+const FN_HASHES = new WeakMap<OIDCRequestFunction | OIDCRefreshFunction, number>();
+/* Put the no function hash in the map. */
+FN_HASHES.set(NO_FUNCTION, FN_HASH_COUNTER);
+
+/** @internal */
+export class TokenEntry {
+  tokenResult: OIDCRequestTokenResult;
+  serverResult: OIDCMechanismServerStep1;
+  expiration: number;
+
+  /**
+   * Instantiate the entry.
+   */
+  constructor(
+    tokenResult: OIDCRequestTokenResult,
+    serverResult: OIDCMechanismServerStep1,
+    expiration: number
+  ) {
+    this.tokenResult = tokenResult;
+    this.serverResult = serverResult;
+    this.expiration = expiration;
+  }
+
+  /**
+   * The entry is still valid if the expiration is more than
+   * 5 minutes from the expiration time.
+   */
+  isValid() {
+    return this.expiration - Date.now() > EXPIRATION_BUFFER_MS;
+  }
+}
+
+/**
+ * Cache of OIDC token entries.
+ * @internal
+ */
+export class TokenEntryCache {
+  entries: Map<string, TokenEntry>;
+
+  constructor() {
+    this.entries = new Map();
+  }
+
+  /**
+   * Set an entry in the token cache.
+   */
+  addEntry(
+    address: string,
+    username: string,
+    requestFn: OIDCRequestFunction | null,
+    refreshFn: OIDCRefreshFunction | null,
+    tokenResult: OIDCRequestTokenResult,
+    serverResult: OIDCMechanismServerStep1
+  ): TokenEntry {
+    const entry = new TokenEntry(
+      tokenResult,
+      serverResult,
+      expirationTime(tokenResult.expiresInSeconds)
+    );
+    this.entries.set(cacheKey(address, username, requestFn, refreshFn), entry);
+    return entry;
+  }
+
+  /**
+   * Clear the cache.
+   */
+  clear(): void {
+    this.entries.clear();
+  }
+
+  /**
+   * Delete an entry from the cache.
+   */
+  deleteEntry(
+    address: string,
+    username: string,
+    requestFn: OIDCRequestFunction | null,
+    refreshFn: OIDCRefreshFunction | null
+  ): void {
+    this.entries.delete(cacheKey(address, username, requestFn, refreshFn));
+  }
+
+  /**
+   * Get an entry from the cache.
+   */
+  getEntry(
+    address: string,
+    username: string,
+    requestFn: OIDCRequestFunction | null,
+    refreshFn: OIDCRefreshFunction | null
+  ): TokenEntry | undefined {
+    return this.entries.get(cacheKey(address, username, requestFn, refreshFn));
+  }
+
+  /**
+   * Delete all expired entries from the cache.
+   */
+  deleteExpiredEntries(): void {
+    for (const [key, entry] of this.entries) {
+      if (!entry.isValid()) {
+        this.entries.delete(key);
+      }
+    }
+  }
+}
+
+/**
+ * Get an expiration time in milliseconds past epoch. Defaults to immediate.
+ */
+function expirationTime(expiresInSeconds?: number): number {
+  return Date.now() + (expiresInSeconds ?? DEFAULT_EXPIRATION_SECS) * 1000;
+}
+
+/**
+ * Create a cache key from the address and username.
+ */
+function cacheKey(
+  address: string,
+  username: string,
+  requestFn: OIDCRequestFunction | null,
+  refreshFn: OIDCRefreshFunction | null
+): string {
+  return `${address}-${username}-${hashFunctions(requestFn, refreshFn)}`;
+}
+
+/**
+ * Get the hash string for the request and refresh functions.
+ */
+function hashFunctions(
+  requestFn: OIDCRequestFunction | null,
+  refreshFn: OIDCRefreshFunction | null
+): string {
+  let requestHash = FN_HASHES.get(requestFn || NO_FUNCTION);
+  let refreshHash = FN_HASHES.get(refreshFn || NO_FUNCTION);
+  if (!requestHash && requestFn) {
+    // Create a new one for the function and put it in the map.
+    FN_HASH_COUNTER++;
+    requestHash = FN_HASH_COUNTER;
+    FN_HASHES.set(requestFn, FN_HASH_COUNTER);
+  }
+  if (!refreshHash && refreshFn) {
+    // Create a new one for the function and put it in the map.
+    FN_HASH_COUNTER++;
+    refreshHash = FN_HASH_COUNTER;
+    FN_HASHES.set(refreshFn, FN_HASH_COUNTER);
+  }
+  return `${requestHash}-${refreshHash}`;
+}

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

@@ -0,0 +1,21 @@
+import type { Document } from 'bson';
+
+import type { Connection } from '../../connection';
+import type { MongoCredentials } from '../mongo_credentials';
+
+export interface Workflow {
+  /**
+   * All device workflows must implement this method in order to get the access
+   * token and then call authenticate with it.
+   */
+  execute(
+    connection: Connection,
+    credentials: MongoCredentials,
+    reauthenticate?: boolean
+  ): Promise<Document>;
+
+  /**
+   * Get the document to add for speculative authentication.
+   */
+  speculativeAuth(): Promise<Document>;
+}

package/src/cmap/auth/mongodb_oidc.ts

@@ -1,20 +1,28 @@
+import { MongoInvalidArgumentError, MongoMissingCredentialsError } from '../../error';
+import type { HandshakeDocument } from '../connect';
+import { type AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
+import { AwsServiceWorkflow } from './mongodb_oidc/aws_service_workflow';
+import { CallbackWorkflow } from './mongodb_oidc/callback_workflow';
+import type { Workflow } from './mongodb_oidc/workflow';
+
 /**
- * TODO: NODE-5035: Make API public
- *
- * @internal */
+ * @public
+ * @experimental
+ */
 export interface OIDCMechanismServerStep1 {
-  authorizeEndpoint?: string;
+  authorizationEndpoint?: string;
   tokenEndpoint?: string;
-  deviceAuthorizeEndpoint?: string;
+  deviceAuthorizationEndpoint?: string;
   clientId: string;
   clientSecret?: string;
   requestScopes?: string[];
 }
 
 /**
- * TODO: NODE-5035: Make API public
- *
- * @internal */
+ * @public
+ * @experimental
+ */
 export interface OIDCRequestTokenResult {
   accessToken: string;
   expiresInSeconds?: number;
@@ -22,18 +30,94 @@ export interface OIDCRequestTokenResult {
 }
 
 /**
- * TODO: NODE-5035: Make API public
- *
- * @internal */
+ * @public
+ * @experimental
+ */
 export type OIDCRequestFunction = (
-  idl: OIDCMechanismServerStep1
+  principalName: string,
+  serverResult: OIDCMechanismServerStep1,
+  timeout: AbortSignal | number
 ) => Promise<OIDCRequestTokenResult>;
 
 /**
- * TODO: NODE-5035: Make API public
- *
- * @internal */
+ * @public
+ * @experimental
+ */
 export type OIDCRefreshFunction = (
-  idl: OIDCMechanismServerStep1,
-  result: OIDCRequestTokenResult
+  principalName: string,
+  serverResult: OIDCMechanismServerStep1,
+  result: OIDCRequestTokenResult,
+  timeout: AbortSignal | number
 ) => Promise<OIDCRequestTokenResult>;
+
+type ProviderName = 'aws' | 'callback';
+
+/** @internal */
+export const OIDC_WORKFLOWS: Map<ProviderName, Workflow> = new Map();
+OIDC_WORKFLOWS.set('callback', new CallbackWorkflow());
+OIDC_WORKFLOWS.set('aws', new AwsServiceWorkflow());
+
+/**
+ * OIDC auth provider.
+ * @experimental
+ */
+export class MongoDBOIDC extends AuthProvider {
+  /**
+   * Instantiate the auth provider.
+   */
+  constructor() {
+    super();
+  }
+
+  /**
+   * Authenticate using OIDC
+   */
+  override async auth(authContext: AuthContext): Promise<void> {
+    const { connection, credentials, response, reauthenticating } = authContext;
+
+    if (response?.speculativeAuthenticate) {
+      return;
+    }
+
+    if (!credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+
+    const workflow = getWorkflow(credentials);
+
+    await workflow.execute(connection, credentials, reauthenticating);
+  }
+
+  /**
+   * Add the speculative auth for the initial handshake.
+   */
+  override async prepare(
+    handshakeDoc: HandshakeDocument,
+    authContext: AuthContext
+  ): Promise<HandshakeDocument> {
+    const { credentials } = authContext;
+
+    if (!credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+
+    const workflow = getWorkflow(credentials);
+
+    const result = await workflow.speculativeAuth();
+    return { ...handshakeDoc, ...result };
+  }
+}
+
+/**
+ * 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/plain.ts

@@ -1,16 +1,16 @@
 import { Binary } from '../../bson';
 import { MongoMissingCredentialsError } from '../../error';
-import { Callback, ns } from '../../utils';
+import { ns } from '../../utils';
 import { AuthContext, AuthProvider } from './auth_provider';
 
 export class Plain extends AuthProvider {
-  override auth(authContext: AuthContext, callback: Callback): void {
+  override async auth(authContext: AuthContext): Promise<void> {
     const { connection, credentials } = authContext;
     if (!credentials) {
-      return callback(new MongoMissingCredentialsError('AuthContext must provide credentials.'));
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
     }
-    const username = credentials.username;
-    const password = credentials.password;
+
+    const { username, password } = credentials;
 
     const payload = new Binary(Buffer.from(`\x00${username}\x00${password}`));
     const command = {
@@ -20,6 +20,6 @@ export class Plain extends AuthProvider {
       autoAuthorize: 1
     };
 
-    connection.command(ns('$external.$cmd'), command, undefined, callback);
+    await connection.commandAsync(ns('$external.$cmd'), command, undefined);
   }
 }

package/src/cmap/auth/providers.ts

@@ -8,12 +8,12 @@ export const AuthMechanism = Object.freeze({
   MONGODB_SCRAM_SHA1: 'SCRAM-SHA-1',
   MONGODB_SCRAM_SHA256: 'SCRAM-SHA-256',
   MONGODB_X509: 'MONGODB-X509',
-  /** @internal TODO: NODE-5035: Make mechanism public. */
+  /** @experimental */
   MONGODB_OIDC: 'MONGODB-OIDC'
 } as const);
 
 /** @public */
-export type AuthMechanism = typeof AuthMechanism[keyof typeof AuthMechanism];
+export type AuthMechanism = (typeof AuthMechanism)[keyof typeof AuthMechanism];
 
 /** @internal */
 export const AUTH_MECHS_AUTH_SRC_EXTERNAL = new Set<AuthMechanism>([