@depup/mongodb 7.1.0-depup.0

package/src/cmap/auth/mongodb_oidc.ts

@@ -0,0 +1,185 @@
+import type { Document } from '../../bson';
+import { MongoInvalidArgumentError, MongoMissingCredentialsError } from '../../error';
+import type { HandshakeDocument } from '../connect';
+import type { Connection } from '../connection';
+import { type AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
+import { AutomatedCallbackWorkflow } from './mongodb_oidc/automated_callback_workflow';
+import { callback as azureCallback } from './mongodb_oidc/azure_machine_workflow';
+import { callback as gcpCallback } from './mongodb_oidc/gcp_machine_workflow';
+import { callback as k8sCallback } from './mongodb_oidc/k8s_machine_workflow';
+import { TokenCache } from './mongodb_oidc/token_cache';
+import { callback as testCallback } 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
+ */
+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
+ */
+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
+ */
+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;
+}
+
+/**
+ * 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
+ */
+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 token audience for GCP and Azure. */
+  tokenAudience?: string;
+}
+
+/**
+ * The signature of the human or machine callback functions.
+ * @public
+ */
+export type OIDCCallbackFunction = (params: OIDCCallbackParams) => Promise<OIDCResponse>;
+
+/** The current version of OIDC implementation. */
+export const OIDC_VERSION = 1;
+
+type EnvironmentName = 'test' | 'azure' | 'gcp' | 'k8s' | undefined;
+
+/** @internal */
+export interface Workflow {
+  cache: TokenCache;
+
+  /**
+   * 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,
+    response?: 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(connection: Connection, credentials: MongoCredentials): Promise<Document>;
+}
+
+/** @internal */
+export const OIDC_WORKFLOWS: Map<EnvironmentName, () => Workflow> = new Map();
+OIDC_WORKFLOWS.set('test', () => new AutomatedCallbackWorkflow(new TokenCache(), testCallback));
+OIDC_WORKFLOWS.set('azure', () => new AutomatedCallbackWorkflow(new TokenCache(), azureCallback));
+OIDC_WORKFLOWS.set('gcp', () => new AutomatedCallbackWorkflow(new TokenCache(), gcpCallback));
+OIDC_WORKFLOWS.set('k8s', () => new AutomatedCallbackWorkflow(new TokenCache(), k8sCallback));
+
+/**
+ * OIDC auth provider.
+ */
+export class MongoDBOIDC extends AuthProvider {
+  workflow: Workflow;
+
+  /**
+   * Instantiate the auth provider.
+   */
+  constructor(workflow?: Workflow) {
+    super();
+    if (!workflow) {
+      throw new MongoInvalidArgumentError('No workflow provided to the OIDC auth provider.');
+    }
+    this.workflow = workflow;
+  }
+
+  /**
+   * Authenticate using OIDC
+   */
+  override async auth(authContext: AuthContext): Promise<void> {
+    const { connection, reauthenticating, response } = authContext;
+    if (response?.speculativeAuthenticate?.done && !reauthenticating) {
+      return;
+    }
+    const credentials = getCredentials(authContext);
+    if (reauthenticating) {
+      await this.workflow.reauthenticate(connection, credentials);
+    } else {
+      await this.workflow.execute(connection, credentials, response);
+    }
+  }
+
+  /**
+   * Add the speculative auth for the initial handshake.
+   */
+  override async prepare(
+    handshakeDoc: HandshakeDocument,
+    authContext: AuthContext
+  ): Promise<HandshakeDocument> {
+    const { connection } = authContext;
+    const credentials = getCredentials(authContext);
+    const result = await this.workflow.speculativeAuth(connection, credentials);
+    return { ...handshakeDoc, ...result };
+  }
+}
+
+/**
+ * Get credentials from the auth context, throwing if they do not exist.
+ */
+function getCredentials(authContext: AuthContext): MongoCredentials {
+  const { credentials } = authContext;
+  if (!credentials) {
+    throw new MongoMissingCredentialsError(MISSING_CREDENTIALS_ERROR);
+  }
+  return credentials;
+}

package/src/cmap/auth/plain.ts

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

package/src/cmap/auth/providers.ts

@@ -0,0 +1,22 @@
+/** @public */
+export const AuthMechanism = Object.freeze({
+  MONGODB_AWS: 'MONGODB-AWS',
+  MONGODB_DEFAULT: 'DEFAULT',
+  MONGODB_GSSAPI: 'GSSAPI',
+  MONGODB_PLAIN: 'PLAIN',
+  MONGODB_SCRAM_SHA1: 'SCRAM-SHA-1',
+  MONGODB_SCRAM_SHA256: 'SCRAM-SHA-256',
+  MONGODB_X509: 'MONGODB-X509',
+  MONGODB_OIDC: 'MONGODB-OIDC'
+} as const);
+
+/** @public */
+export type AuthMechanism = (typeof AuthMechanism)[keyof typeof AuthMechanism];
+
+/** @internal */
+export const AUTH_MECHS_AUTH_SRC_EXTERNAL = new Set<AuthMechanism>([
+  AuthMechanism.MONGODB_GSSAPI,
+  AuthMechanism.MONGODB_AWS,
+  AuthMechanism.MONGODB_OIDC,
+  AuthMechanism.MONGODB_X509
+]);

package/src/cmap/auth/scram.ts

@@ -0,0 +1,344 @@
+import { saslprep } from '@mongodb-js/saslprep';
+import * as crypto from 'crypto';
+
+import { Binary, type Document } from '../../bson';
+import {
+  MongoInvalidArgumentError,
+  MongoMissingCredentialsError,
+  MongoRuntimeError
+} from '../../error';
+import { ns, randomBytes } from '../../utils';
+import type { HandshakeDocument } from '../connect';
+import { type AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
+import { AuthMechanism } from './providers';
+
+type CryptoMethod = 'sha1' | 'sha256';
+
+class ScramSHA extends AuthProvider {
+  cryptoMethod: CryptoMethod;
+
+  constructor(cryptoMethod: CryptoMethod) {
+    super();
+    this.cryptoMethod = cryptoMethod || 'sha1';
+  }
+
+  override async prepare(
+    handshakeDoc: HandshakeDocument,
+    authContext: AuthContext
+  ): Promise<HandshakeDocument> {
+    const cryptoMethod = this.cryptoMethod;
+    const credentials = authContext.credentials;
+    if (!credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+
+    const nonce = await randomBytes(24);
+    // store the nonce for later use
+    authContext.nonce = nonce;
+
+    const request = {
+      ...handshakeDoc,
+      speculativeAuthenticate: {
+        ...makeFirstMessage(cryptoMethod, credentials, nonce),
+        db: credentials.source
+      }
+    };
+
+    return request;
+  }
+
+  override async auth(authContext: AuthContext) {
+    const { reauthenticating, response } = authContext;
+    if (response?.speculativeAuthenticate && !reauthenticating) {
+      return await continueScramConversation(
+        this.cryptoMethod,
+        response.speculativeAuthenticate,
+        authContext
+      );
+    }
+    return await executeScram(this.cryptoMethod, authContext);
+  }
+}
+
+function cleanUsername(username: string) {
+  return username.replace('=', '=3D').replace(',', '=2C');
+}
+
+function clientFirstMessageBare(username: string, nonce: Buffer) {
+  // NOTE: This is done b/c Javascript uses UTF-16, but the server is hashing in UTF-8.
+  // Since the username is not sasl-prep-d, we need to do this here.
+  return Buffer.concat([
+    Buffer.from('n=', 'utf8'),
+    Buffer.from(username, 'utf8'),
+    Buffer.from(',r=', 'utf8'),
+    Buffer.from(nonce.toString('base64'), 'utf8')
+  ]);
+}
+
+function makeFirstMessage(
+  cryptoMethod: CryptoMethod,
+  credentials: MongoCredentials,
+  nonce: Buffer
+) {
+  const username = cleanUsername(credentials.username);
+  const mechanism =
+    cryptoMethod === 'sha1' ? AuthMechanism.MONGODB_SCRAM_SHA1 : AuthMechanism.MONGODB_SCRAM_SHA256;
+
+  // NOTE: This is done b/c Javascript uses UTF-16, but the server is hashing in UTF-8.
+  // Since the username is not sasl-prep-d, we need to do this here.
+  return {
+    saslStart: 1,
+    mechanism,
+    payload: new Binary(
+      Buffer.concat([Buffer.from('n,,', 'utf8'), clientFirstMessageBare(username, nonce)])
+    ),
+    autoAuthorize: 1,
+    options: { skipEmptyExchange: true }
+  };
+}
+
+async function executeScram(cryptoMethod: CryptoMethod, authContext: AuthContext): Promise<void> {
+  const { connection, credentials } = authContext;
+  if (!credentials) {
+    throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+  }
+  if (!authContext.nonce) {
+    throw new MongoInvalidArgumentError('AuthContext must contain a valid nonce property');
+  }
+  const nonce = authContext.nonce;
+  const db = credentials.source;
+
+  const saslStartCmd = makeFirstMessage(cryptoMethod, credentials, nonce);
+  const response = await connection.command(ns(`${db}.$cmd`), saslStartCmd, undefined);
+  await continueScramConversation(cryptoMethod, response, authContext);
+}
+
+async function continueScramConversation(
+  cryptoMethod: CryptoMethod,
+  response: Document,
+  authContext: AuthContext
+): Promise<void> {
+  const connection = authContext.connection;
+  const credentials = authContext.credentials;
+  if (!credentials) {
+    throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+  }
+  if (!authContext.nonce) {
+    throw new MongoInvalidArgumentError('Unable to continue SCRAM without valid nonce');
+  }
+  const nonce = authContext.nonce;
+
+  const db = credentials.source;
+  const username = cleanUsername(credentials.username);
+  const password = credentials.password;
+
+  const processedPassword =
+    cryptoMethod === 'sha256' ? saslprep(password) : passwordDigest(username, password);
+
+  const payload: Binary = Buffer.isBuffer(response.payload)
+    ? new Binary(response.payload)
+    : response.payload;
+
+  const dict = parsePayload(payload);
+
+  const iterations = parseInt(dict.i, 10);
+  if (iterations && iterations < 4096) {
+    // TODO(NODE-3483)
+    throw new MongoRuntimeError(`Server returned an invalid iteration count ${iterations}`);
+  }
+
+  const salt = dict.s;
+  const rnonce = dict.r;
+  if (rnonce.startsWith('nonce')) {
+    // TODO(NODE-3483)
+    throw new MongoRuntimeError(`Server returned an invalid nonce: ${rnonce}`);
+  }
+
+  // Set up start of proof
+  const withoutProof = `c=biws,r=${rnonce}`;
+  const saltedPassword = HI(
+    processedPassword,
+    Buffer.from(salt, 'base64'),
+    iterations,
+    cryptoMethod
+  );
+
+  const clientKey = HMAC(cryptoMethod, saltedPassword, 'Client Key');
+  const serverKey = HMAC(cryptoMethod, saltedPassword, 'Server Key');
+  const storedKey = H(cryptoMethod, clientKey);
+  const authMessage = [
+    clientFirstMessageBare(username, nonce),
+    payload.toString('utf8'),
+    withoutProof
+  ].join(',');
+
+  const clientSignature = HMAC(cryptoMethod, storedKey, authMessage);
+  const clientProof = `p=${xor(clientKey, clientSignature)}`;
+  const clientFinal = [withoutProof, clientProof].join(',');
+
+  const serverSignature = HMAC(cryptoMethod, serverKey, authMessage);
+  const saslContinueCmd = {
+    saslContinue: 1,
+    conversationId: response.conversationId,
+    payload: new Binary(Buffer.from(clientFinal))
+  };
+
+  const r = await connection.command(ns(`${db}.$cmd`), saslContinueCmd, undefined);
+  const parsedResponse = parsePayload(r.payload);
+
+  if (!compareDigest(Buffer.from(parsedResponse.v, 'base64'), serverSignature)) {
+    throw new MongoRuntimeError('Server returned an invalid signature');
+  }
+
+  if (r.done !== false) {
+    // If the server sends r.done === true we can save one RTT
+    return;
+  }
+
+  const retrySaslContinueCmd = {
+    saslContinue: 1,
+    conversationId: r.conversationId,
+    payload: Buffer.alloc(0)
+  };
+
+  await connection.command(ns(`${db}.$cmd`), retrySaslContinueCmd, undefined);
+}
+
+function parsePayload(payload: Binary) {
+  const payloadStr = payload.toString('utf8');
+  const dict: Document = {};
+  const parts = payloadStr.split(',');
+  for (let i = 0; i < parts.length; i++) {
+    const valueParts = (parts[i].match(/^([^=]*)=(.*)$/) ?? []).slice(1);
+    dict[valueParts[0]] = valueParts[1];
+  }
+  return dict;
+}
+
+function passwordDigest(username: string, password: string) {
+  if (typeof username !== 'string') {
+    throw new MongoInvalidArgumentError('Username must be a string');
+  }
+
+  if (typeof password !== 'string') {
+    throw new MongoInvalidArgumentError('Password must be a string');
+  }
+
+  if (password.length === 0) {
+    throw new MongoInvalidArgumentError('Password cannot be empty');
+  }
+
+  let md5: crypto.Hash;
+  try {
+    md5 = crypto.createHash('md5');
+  } catch (err) {
+    if (crypto.getFips()) {
+      // This error is (slightly) more helpful than what comes from OpenSSL directly, e.g.
+      // 'Error: error:060800C8:digital envelope routines:EVP_DigestInit_ex:disabled for FIPS'
+      throw new Error('Auth mechanism SCRAM-SHA-1 is not supported in FIPS mode');
+    }
+    throw err;
+  }
+  md5.update(`${username}:mongo:${password}`, 'utf8');
+  return md5.digest('hex');
+}
+
+// XOR two buffers
+function xor(a: Buffer, b: Buffer) {
+  if (!Buffer.isBuffer(a)) {
+    a = Buffer.from(a);
+  }
+
+  if (!Buffer.isBuffer(b)) {
+    b = Buffer.from(b);
+  }
+
+  const length = Math.max(a.length, b.length);
+  const res = [];
+
+  for (let i = 0; i < length; i += 1) {
+    res.push(a[i] ^ b[i]);
+  }
+
+  return Buffer.from(res).toString('base64');
+}
+
+function H(method: CryptoMethod, text: Buffer) {
+  return crypto.createHash(method).update(text).digest();
+}
+
+function HMAC(method: CryptoMethod, key: Buffer, text: Buffer | string) {
+  return crypto.createHmac(method, key).update(text).digest();
+}
+
+interface HICache {
+  [key: string]: Buffer;
+}
+
+let _hiCache: HICache = {};
+let _hiCacheCount = 0;
+function _hiCachePurge() {
+  _hiCache = {};
+  _hiCacheCount = 0;
+}
+
+const hiLengthMap = {
+  sha256: 32,
+  sha1: 20
+};
+
+function HI(data: string, salt: Buffer, iterations: number, cryptoMethod: CryptoMethod) {
+  // omit the work if already generated
+  const key = [data, salt.toString('base64'), iterations].join('_');
+  if (_hiCache[key] != null) {
+    return _hiCache[key];
+  }
+
+  // generate the salt
+  const saltedData = crypto.pbkdf2Sync(
+    data,
+    salt,
+    iterations,
+    hiLengthMap[cryptoMethod],
+    cryptoMethod
+  );
+
+  // cache a copy to speed up the next lookup, but prevent unbounded cache growth
+  if (_hiCacheCount >= 200) {
+    _hiCachePurge();
+  }
+
+  _hiCache[key] = saltedData;
+  _hiCacheCount += 1;
+  return saltedData;
+}
+
+function compareDigest(lhs: Buffer, rhs: Uint8Array) {
+  if (lhs.length !== rhs.length) {
+    return false;
+  }
+
+  if (typeof crypto.timingSafeEqual === 'function') {
+    return crypto.timingSafeEqual(lhs, rhs);
+  }
+
+  let result = 0;
+  for (let i = 0; i < lhs.length; i++) {
+    result |= lhs[i] ^ rhs[i];
+  }
+
+  return result === 0;
+}
+
+export class ScramSHA1 extends ScramSHA {
+  constructor() {
+    super('sha1');
+  }
+}
+
+export class ScramSHA256 extends ScramSHA {
+  constructor() {
+    super('sha256');
+  }
+}

package/src/cmap/auth/x509.ts

@@ -0,0 +1,43 @@
+import type { Document } from '../../bson';
+import { MongoMissingCredentialsError } from '../../error';
+import { ns } from '../../utils';
+import type { HandshakeDocument } from '../connect';
+import { type AuthContext, AuthProvider } from './auth_provider';
+import type { MongoCredentials } from './mongo_credentials';
+
+export class X509 extends AuthProvider {
+  override async prepare(
+    handshakeDoc: HandshakeDocument,
+    authContext: AuthContext
+  ): Promise<HandshakeDocument> {
+    const { credentials } = authContext;
+    if (!credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+    return { ...handshakeDoc, speculativeAuthenticate: x509AuthenticateCommand(credentials) };
+  }
+
+  override async auth(authContext: AuthContext) {
+    const connection = authContext.connection;
+    const credentials = authContext.credentials;
+    if (!credentials) {
+      throw new MongoMissingCredentialsError('AuthContext must provide credentials.');
+    }
+    const response = authContext.response;
+
+    if (response?.speculativeAuthenticate) {
+      return;
+    }
+
+    await connection.command(ns('$external.$cmd'), x509AuthenticateCommand(credentials), undefined);
+  }
+}
+
+function x509AuthenticateCommand(credentials: MongoCredentials) {
+  const command: Document = { authenticate: 1, mechanism: 'MONGODB-X509' };
+  if (credentials.username) {
+    command.user = credentials.username;
+  }
+
+  return command;
+}