feat: UUID convenience class (#425)

Adds a class that encapsulates generating and interacting with UUIDs stored in the BSON Binary type. Adds `to/from` UUID Binary helpers. Adds cross platform crypto API usage for secure random number generation when available.

Author: steffenagger

package-lock.json

@@ -63,7 +63,8 @@
     "ts-node": "^9.0.0",
     "typedoc": "^0.18.0",
     "typescript": "^4.0.2",
-    "typescript-cached-transpile": "0.0.6"
+    "typescript-cached-transpile": "0.0.6",
+    "uuid": "^8.3.2"
   },
   "config": {
     "native": false

package.json

@@ -1,7 +1,8 @@
 import { Buffer } from 'buffer';
 import { ensureBuffer } from './ensure_buffer';
+import { uuidHexStringToBuffer } from './uuid_utils';
+import { UUID, UUIDExtended } from './uuid';
 import type { EJSONOptions } from './extended_json';
-import { parseUUID, UUIDExtended } from './uuid';
 
 /** @public */
 export type BinarySequence = Uint8Array | Buffer | number[];
@@ -230,6 +231,17 @@ export class Binary {
     };
   }
 
+  /** @internal */
+  toUUID(): UUID {
+    if (this.sub_type === Binary.SUBTYPE_UUID) {
+      return new UUID(this.buffer.slice(0, this.position));
+    }
+
+    throw new Error(
+      `Binary sub_type "${this.sub_type}" is not supported for converting to UUID. Only "${Binary.SUBTYPE_UUID}" is currently supported.`
+    );
+  }
+
   /** @internal */
   static fromExtendedJSON(
     doc: BinaryExtendedLegacy | BinaryExtended | UUIDExtended,
@@ -250,7 +262,7 @@ export class Binary {
       }
     } else if ('$uuid' in doc) {
       type = 4;
-      data = Buffer.from(parseUUID(doc.$uuid));
+      data = uuidHexStringToBuffer(doc.$uuid);
     }
     if (!data) {
       throw new TypeError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);

src/binary.ts

@@ -12,6 +12,7 @@ import { Map } from './map';
 import { MaxKey } from './max_key';
 import { MinKey } from './min_key';
 import { ObjectId } from './objectid';
+import { UUID } from './uuid';
 import { calculateObjectSize as internalCalculateObjectSize } from './parser/calculate_size';
 // Parts of the parser
 import { deserialize as internalDeserialize, DeserializeOptions } from './parser/deserializer';
@@ -81,6 +82,7 @@ export {
   DBRef,
   Binary,
   ObjectId,
+  UUID,
   Long,
   Timestamp,
   Double,

src/bson.ts

@@ -229,7 +229,7 @@ export class ObjectId {
       typeof otherId === 'string' &&
       ObjectId.isValid(otherId) &&
       otherId.length === 12 &&
-      this.id instanceof Buffer
+      Buffer.isBuffer(this.id)
     ) {
       return otherId === this.id.toString('binary');
     }
@@ -315,7 +315,7 @@ export class ObjectId {
       return true;
     }
 
-    if (id instanceof Buffer && id.length === 12) {
+    if (Buffer.isBuffer(id) && id.length === 12) {
       return true;
     }
 

src/objectid.ts

@@ -1,5 +1,7 @@
 import { Buffer } from 'buffer';
 
+type RandomBytesFunction = (size: number) => Uint8Array;
+
 /**
  * Normalizes our expected stringified form of a function across versions of node
  * @param fn - The function to stringify
@@ -8,11 +10,20 @@ export function normalizedFunctionString(fn: Function): string {
   return fn.toString().replace('function(', 'function (');
 }
 
-function insecureRandomBytes(size: number): Uint8Array {
+const isReactNative =
+  typeof global.navigator === 'object' && global.navigator.product === 'ReactNative';
+
+const insecureWarning = isReactNative
+  ? 'BSON: For React Native please polyfill crypto.getRandomValues, e.g. using: https://www.npmjs.com/package/react-native-get-random-values.'
+  : 'BSON: No cryptographic implementation for random bytes present, falling back to a less secure implementation.';
+
+const insecureRandomBytes: RandomBytesFunction = function insecureRandomBytes(size: number) {
+  console.warn(insecureWarning);
+
   const result = Buffer.alloc(size);
   for (let i = 0; i < size; ++i) result[i] = Math.floor(Math.random() * 256);
   return result;
-}
+};
 
 /* We do not want to have to include DOM types just for this check */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -22,22 +33,34 @@ declare let require: Function;
 declare let global: any;
 declare const self: unknown;
 
-export let randomBytes = insecureRandomBytes;
-if (typeof window !== 'undefined' && window.crypto && window.crypto.getRandomValues) {
-  randomBytes = size => window.crypto.getRandomValues(Buffer.alloc(size));
-} else {
+const detectRandomBytes = (): RandomBytesFunction => {
+  if (typeof window !== 'undefined') {
+    // browser crypto implementation(s)
+    const target = window.crypto || window.msCrypto; // allow for IE11
+    if (target && target.getRandomValues) {
+      return size => target.getRandomValues(Buffer.alloc(size));
+    }
+  }
+
+  if (typeof global !== 'undefined' && global.crypto && global.crypto.getRandomValues) {
+    // allow for RN packages such as https://www.npmjs.com/package/react-native-get-random-values to populate global
+    return size => global.crypto.getRandomValues(Buffer.alloc(size));
+  }
+
+  let requiredRandomBytes: RandomBytesFunction | null | undefined;
   try {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    randomBytes = require('crypto').randomBytes;
+    requiredRandomBytes = require('crypto').randomBytes;
   } catch (e) {
     // keep the fallback
   }
 
   // NOTE: in transpiled cases the above require might return null/undefined
-  if (randomBytes == null) {
-    randomBytes = insecureRandomBytes;
-  }
-}
+
+  return requiredRandomBytes || insecureRandomBytes;
+};
+
+export const randomBytes = detectRandomBytes();
 
 export function isUint8Array(value: unknown): value is Uint8Array {
   return Object.prototype.toString.call(value) === '[object Uint8Array]';