Global Modules

Returns

Returns a JSON Web Token string encoded for the provided payload.

Consider the following JWT claims object:

{
  "sub": "1234567890",
  "name": "Joe Example",
  "iat": 1565721223187
}

We can encode the claims object as a JWT string by calling utils.jwt.encode(). The following function encodes the JWT using the HS512 signing method and the secret "SuperSecret":

exports = function() {
  const signingMethod = "HS512";
  const payload = {
    "sub": "1234567890",
    "name": "Joe Example",
    "iat": 1565721223187
  };
  const secret = "SuperSecret";
  return utils.jwt.encode(signingMethod, payload, secret);
}

"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvZSBTY2htb2UiLCJpYXQiOjE1NjU3MjEyMjMxODd9.-QL15ldu2BYuJokNWT6YRiwZQIiIpvq6Kyv-C6qslNdNiUVxo8zqLJZ1iEkNf2yZKMIrQuMCtIC1tzd2H31AxA"

Returns

If returnHeader is false, returns the decoded EJSON payload.

If returnHeader is true, returns an object that contains the JOSE header in the header field and the decoded EJSON payload in the payload field.

{
  "header": {
    "<JOSE Header Field>": <JOSE Header Value>,
    ...
  },
  "payload": {
    "<JWT Claim Field>": <JWT Claim Value>,
    ...
  }
}

Consider the following signed JWT string:

"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvZSBTY2htb2UiLCJpYXQiOjE1NjU3MjEyMjMxODd9.-QL15ldu2BYuJokNWT6YRiwZQIiIpvq6Kyv-C6qslNdNiUVxo8zqLJZ1iEkNf2yZKMIrQuMCtIC1tzd2H31AxA"

The JWT was signed using the HS512 signing method with the secret value "SuperSecret". We can decode the JWT's claims object utils.jwt.decode(). The following function decodes the JWT string into an EJSON object:

exports = function(jwtString) {
  const key = "SuperSecret";
  return utils.jwt.decode(jwtString, key, false, ["HS512"]);
}

{
  "sub": "1234567890",
  "name": "Joe Example",
  "iat": { "$numberDouble": 1565721223187 }
}

Returns

A BSON Binary object that contains the text string encrypted with the specified encryption type and key.

Assume that we have defined a value named aesEncryptionKey that contains the following 32-byte AES encryption key:

"603082712271C525E087BD999A4E0738"

With this AES key, we can encrypt a message into a base64 string using the following function:

exports = function() {
  const message = "MongoDB is great!"
  const key = context.values.get("aesEncryptionKey");
  const encryptedMessage = utils.crypto.encrypt("aes", message, key);
  return encryptedMessage.toBase64();
}

"WPBuIvJ6Bity43Uh822dW8QlVYVJaFUiDeUjlTiJXzptUuTYIKPlXekBQAJb"

Returns

A BSON Binary object that contains the decrypted message.

If the provided encrypted message was encrypted with the specified method and key, then the decrypted message is identical to the original message.

Assume that we have defined a Value named aesEncryptionKey that contains the following 32-byte AES encryption key:

"603082712271C525E087BD999A4E0738"

We can use this AES key to decrypt any base64 string that was encrypted with the same key using the following function:

exports = function(encryptedMessage) {
  // The encrypted message must be a BSON.Binary
  if(typeof encryptedMessage === "string") {
    encryptedMessage = BSON.Binary.fromBase64(encryptedMessage)
  }
  const key = context.values.get("aesEncryptionKey");
  const decryptedMessage = utils.crypto.decrypt("aes", encryptedMessage, key);
  return decryptedMessage.text();
}

"MongoDB is great!"

Returns

A BSON.Binary cryptographic signature for the message signed using the specified private key.

Assume that we have defined a value named rsaPrivateKey that contains the following RSA private key:

-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQDVsEjse2qO4v3p8RM/q8Rqzloc1lee34yoYuKZ2cemuUu8Jpc7
KFO1+aJpXdbSPZNhGLdANn8f2oMIZ1R9hgEJRn/Qm/YyC4RPTGg55nzHqSlziNZJ
JAyEUyU7kx5+Kb6ktgojhk8ocZRkorM8FEylkrKzgSrfay0PcWHPsKlmeQIDAQAB
AoGAHlVK1L7kLmpMbuP4voYMeLjYE9XdVEEZf2GiFwLSE3mkJY44033y/Bb2lgxr
DScOf675fFUAEK59ATlhxfu6s6rgx+g9qQQ+mL74YZWPqiZHBPjyMRaBalDVC4QF
YJ+DopFcB8hY2ElXnbK70ALmVYNjw3RdmC97h0YfOsQcWW0CQQD18aeuPNicVnse
Ku22vvhvQYlabaQh4xdkEIxz1TthZj48f61wZwEMipYqOAc5XEtDlNnxgeipv0yF
RHstUjwXAkEA3m0Br/U/vC9evuXppWbONana08KLgfELyd3Uw9jG7VKJZTBH5mS8
7CB68aEF8egrJpo8Ss8BkWrvCxYDb4Y77wJAUlbOMZozVtvpKidrIFR9Lho91uWA
Hsw9h4W20AzibXBig7SnJ0uE4WMAdS/+0yhgFkceVCmO8E2YW8Gaj4jJjwJASxtg
AHy+ItuUEL4uIW4Pn8tVW0BMP3qX0niXyfI/ag/+2S5uePv3V3y4RzNqgH83Yved
+FziWKpVQdcTHeuj/QJBAJl1G3WFruk0llIoKKbKljaEiCm1WCTcuEPbdOtkJYvO
9ZYQg/fji70FERkq2KHtY7aLhCHzy0d4n9xgE/pjV+I=
-----END RSA PRIVATE KEY-----

With this RSA key, we can sign a message using the following function:

exports = function() {
  const message = "MongoDB is great!"
  const rsaPrivateKey = context.values.get("rsaPrivateKey");
  const signature = utils.crypto.sign("rsa", message, rsaPrivateKey, "pss");
  return signature.toBase64();
}

"SpfXcJwPbypArt+XuYQyuZqU52YCAY/sZj2kiuin2b6/RzyM4Ek3n3spOtqZJqxn1tfQavxIX4V+prbs74/pOaQkCLekl9Hoa1xOzSKcGoRd8U+n1+UBY3d3cyODGMpyr8Tim2HZAeLPE/D3Q36/K+jpgjvrJFXsJoAy5/PV7iEGV1fkzogmZtXWDcUUBBTTNPY4qZTzjNhL4RAFOc7Mfci+ojE/lLsNaumUVU1/Eky4vasmyjqunm+ULCcRmgWtGDMGHaQV4OXC2LMUe9GOqd3Q9ghCe0Vlhn25oTh8cXoGpd1Fr8wolNa//9dUqSM+QYDpZJXGLShX/Oa8mPwJZKDKHtqrS+2vE6S4dDWR7zKDza+DeovOeCih71QyuSYMXSz+WWGgfLzv/syhmUXP/mjqgLmJU6Kwg5htajDoylpzLC0BLGT4zDZEwBrq/AjwRs/EPjYdFgGCt1WCbbVlDyXvvH1ekDrzACzumhiMSZNNa+ZH3JmMJxTCQWDfiTeAfkauaaZHKIj2q2/QE7vuAhNcVPJ2YgpXnvnQHJpEZBc/Y3Q6JLxom6+cGC4P//9d++r2cwzXIkqD+wSGZVSVtpm5CLtWMRSK5FX2dv16bM+LE8ozoRvtMUDTrQ8SSSDGxyuYbvN9b2fYYPcWpCMchqOBXV6eZGoMldaHX3Qy5h8="

Returns

A boolean that, if true, indicates whether or not the signature is valid for the provided message and public key.

We received a message with a signature in BSON.Binary format and want to verify that the message was signed with the private key that corresponds to the sender's RSA public key:

-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBANWwSOx7ao7i/enxEz+rxGrOWhzWV57fjKhi4pnZx6a5S7wmlzsoU7X5
omld1tI9k2EYt0A2fx/agwhnVH2GAQlGf9Cb9jILhE9MaDnmfMepKXOI1kkxDIRT
JTuTHn4pvqS2CiOGTyhxlGSiszwUTKWSsrOBKt9rLQ9xYc+wqWZ5AgMBAAE=
-----END RSA PUBLIC KEY-----

With this RSA key, we can verify a message signed with the correspdoning private key using the following function:

exports = function() {
  const rsaPublicKey = context.values.get("rsaPublicKey");
  const message = "MongoDB is great!"
  const signature = BSON.Binary.fromBase64("SpfXcJwPbypArt+XuYQyuZqU52YCAY/sZj2kiuin2b6/RzyM4Ek3n3spOtqZJqxn1tfQavxIX4V+prbs74/pOaQkCLekl9Hoa1xOzSKcGoRd8U+n1+UBY3d3cyODGMpyr8Tim2HZAeLPE/D3Q36/K+jpgjvrJFXsJoAy5/PV7iEGV1fkzogmZtXWDcUUBBTTNPY4qZTzjNhL4RAFOc7Mfci+ojE/lLsNaumUVU1/Eky4vasmyjqunm+ULCcRmgWtGDMGHaQV4OXC2LMUe9GOqd3Q9ghCe0Vlhn25oTh8cXoGpd1Fr8wolNa//9dUqSM+QYDpZJXGLShX/Oa8mPwJZKDKHtqrS+2vE6S4dDWR7zKDza+DeovOeCih71QyuSYMXSz+WWGgfLzv/syhmUXP/mjqgLmJU6Kwg5htajDoylpzLC0BLGT4zDZEwBrq/AjwRs/EPjYdFgGCt1WCbbVlDyXvvH1ekDrzACzumhiMSZNNa+ZH3JmMJxTCQWDfiTeAfkauaaZHKIj2q2/QE7vuAhNcVPJ2YgpXnvnQHJpEZBc/Y3Q6JLxom6+cGC4P//9d++r2cwzXIkqD+wSGZVSVtpm5CLtWMRSK5FX2dv16bM+LE8ozoRvtMUDTrQ8SSSDGxyuYbvN9b2fYYPcWpCMchqOBXV6eZGoMldaHX3Qy5h8=")
  const isValid = utils.crypto.verify("rsa", message, rsaPublicKey, signature, "pss");
  return isValid; // true if the signature matches, else false
}

true

Returns

The signature of the input, in the format specified by output_format.

The following function generates a sha256 signature as a base 64 string:

exports = function() {
  const signature = utils.crypto.hmac(
    "hello!",
    "super-secret",
    "sha256",
    "base64"
  )
  return signature
}

"SUXd6PRMaTXXgBGaGsIHzaDWgTSa6C3D44lRGrvRak0="

Returns

A BSON.Binary object that encodes the hash value for the provided input generated by the specified hashing function.

The following function hashes an input string with sha256:

exports = function() {
  return utils.crypto.hash(
    "sha256",
    "hello!"
  )
}

"zgYJL7lI2f+sfRo3bkBLJrdXW8wR7gWkYV/vT+w6MIs="

Returns

A standard JavaScript object generated from the provided JSON string.

The following function converts a serialized JSON string into an equivalent JavaScript object:

exports = function() {
  const jsonString = `{
    "answer": 42,
    "submittedAt": "2020-03-02T16:50:24.475Z"
  }`;
  return JSON.parse(jsonString);
}

{
  "answer": 42,
  "submittedAt": "2020-03-02T16:50:24.475Z"
}

Returns

A string representation of the provided JavaScript object.

The following function serializes a JavaScript object into an equivalent JSON string:

exports = function() {
  const jsonObject = {
    answer: 42,
    submittedAt: new Date("2020-03-02T16:46:47.977Z")
  };
  return JSON.stringify(jsonObject);
}

"{\"answer\":42,\"submittedAt\":\"2020-03-02T16:46:47.977Z\"}"

Returns

A JavaScript object representation of the provided EJSON string.

The following function converts a serialized EJSON string into an equivalent JavaScript object:

exports = function() {
  const ejsonString = `{
    "answer": {
      "$numberLong": "42"
    },
    "submittedAt": {
      "$date": {
        "$numberLong": "1583167607977"
      }
    }
  }`;
  return EJSON.parse(ejsonString);
}

{
  "answer": {
    "$numberLong": "42"
  },
  "submittedAt": {
    "$date": {
      "$numberLong": "1583167607977"
    }
  }
}

Returns

A string representation of the provided EJSON object.

The following function serializes a JavaScript object into an equivalent EJSON string:

exports = function() {
  const jsonObject = {
    answer: 42,
    submittedAt: new Date("2020-03-02T16:46:47.977Z")
  };
  return EJSON.stringify(jsonObject);
}

"{\"answer\":{\"$numberLong\":\"42\"},\"submittedAt\":{\"$date\":{\"$numberLong\":\"1583167607977\"}}}"

Returns

A BSON.ObjectId object that encodes the specified ObjectId string or a generated ObjectId string if none was specified.

const objectId = new BSON.ObjectId("5e58667d902d38559c802b13");
const generatedObjectId = new BSON.ObjectId();

Returns

A BSON.BSONRegExp object that encodes the provided regular expression pattern and flags.

const regex = BSON.BSONRegExp("the great", "ig");

BSON.Binary.fromHex()

Constructs a BSON.Binary object from data represented as a hexadecimal string.

BSON.Binary.fromHex(
  hexString: string,
  subType?: number
): BSON.Binary

Returns

A BSON.Binary object that encodes the provided hexadecimal string.

const binary = BSON.Binary.fromHex("54657374206d65737361676520706c656173652069676e6f7265=");

BSON.Binary.prototype.toHex()

Converts the BSON.Binary object into a hexadecimal string.

BSON.Binary.prototype.toHex(): string

Returns

A hexadecimal string representation of the provided BSON.Binary object.

export = function() {
  const binary = BSON.Binary.fromHex(
      "54657374206d65737361676520706c656173652069676e6f7265="
    );
  const hexString = binary.toHex();
  return hexString
}

"54657374206d65737361676520706c656173652069676e6f7265="

BSON.Binary.fromBase64()

Constructs a BSON.Binary object from data represented as a base64 string.

BSON.Binary.fromBase64(
  base64String: string,
  subType?: number
): BSON.Binary

Returns

A BSON.Binary object that encodes the provided base64 string.

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");

BSON.Binary.prototype.toBase64()

Converts a BSON.Binary object into a base64 string.

BSON.Binary.prototype.toBase64(): string

Returns

A base64 string representation of the BSON.Binary object.

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const base64String = binary.toBase64();

BSON.Binary.prototype.text()

Converts the BSON.Binary object into a UTF-8 string.

BSON.Binary.prototype.text(): string

Returns

A UTF-8 string representation of the provided BSON.Binary object.

const binary = BSON.Binary.fromBase64("VGVzdCBtZXNzYWdlIHBsZWFzZSBpZ25vcmU=");
const decodedString = binary.text();

Returns

A BSON.Int32 object that encodes the specified integer. Returns 0 if no arguments are supplied.

const int32 = BSON.Int32(42);

BSON.Long(low32, high32)

BSON.Long(low32: number, high32: number): BSON.Long

Constructs a BSON.Long object from two 32-bit integers that represent the low 32 bits and the high 32 bits in the 64-bit Long integer.

Returns

A BSON.Long object that encodes the specified integer. Returns 0 if no arguments are supplied.

BSON.Long encodes using the following formula:

(high32 * (2**32)) + low32

Returns

A BSON.Double object that encodes the specified double. Returns 0 if no argument is supplied.

const double = BSON.Double(1234.5678);

Returns

A BSON.Decimal128 that encodes the provided decimal value.

const double = BSON.Decimal128.fromString("1234.5678910123456");