(DOCSP-33626) Document metadata encryption (#3068)

## Pull Request Info

### Jira

- https://jira.mongodb.org/browse/DOCSP-33626

### Staged Changes

- Node: [Connect to an Atlas App Services
Backend](https://preview-mongodbkrollinsmdb.gatsbyjs.io/realm/DOCSP-33626/sdk/node/app-services/connect-to-app-services-backend/#encrypt-app-metadata)
- Node: [Encrypt a
Realm](https://preview-mongodbkrollinsmdb.gatsbyjs.io/realm/DOCSP-33626/sdk/node/realm-files/encrypt/#encrypt-app-services-app-metadata)
- React Native: [Connect to an Atlas App Services
App](https://preview-mongodbkrollinsmdb.gatsbyjs.io/realm/DOCSP-33626/sdk/react-native/app-services/connect-to-app-services-app/#encrypt-app-metadata)
- React Native: [Encrypt a
Realm](https://preview-mongodbkrollinsmdb.gatsbyjs.io/realm/DOCSP-33626/sdk/react-native/realm-files/encrypt/#encrypt-app-services-app-metadata)

### Review Guidelines


[REVIEWING.md](https://github.com/mongodb/docs-realm/blob/master/REVIEWING.md)

### Animal Wearing a Hat

<img
src="https://i.pinimg.com/432x292/1c/c5/a7/1cc5a7f86c07156be178fff0b659306f.jpg"
width=400>

---------

Co-authored-by: cbullinger <115956901+cbullinger@users.noreply.github.com>

examples/node/scripts/bluehawk-one.sh

@@ -44,7 +44,7 @@ then
 # Bluehawk a single file
 echo "${GREEN_BG_BOLD} Bluehawk: ${CLEAR} ${GREEN}Generate samples from '$FILE_NAME' ${CLEAR}"
 
-bluehawk snip $INPUT_FILE -o $OUTPUT_DIRECTORY --format=rst
+npx bluehawk snip $INPUT_FILE -o $OUTPUT_DIRECTORY --format=rst
 
 # TODO: There's probably a more idiomatic way to do this results filtering.
 GENERATED_FILES=$(find $OUTPUT_DIRECTORY -type f | grep -i $BASE_FILE_NAME)

examples/node/v12/__tests__/metadata.test.js

@@ -0,0 +1,64 @@
+// :snippet-start: imports
+import Realm, { BSON, MetadataMode } from "realm";
+// :snippet-end:
+import { Task } from "./models/models.ts";
+import { APP_ID } from "../config.ts";
+
+describe("Handle Realm Metadata", () => {
+  test("encrypting realm metadata", () => {
+    // :snippet-start: encrypt-metadata
+    // Retrieve encryption key from secure location or create one
+    const encryptionKey = new ArrayBuffer(64);
+
+    // Use encryption key in app configuration
+    const config = {
+      id: APP_ID,
+      // :emphasize-start:
+      metadata: { mode: MetadataMode.Encryption, encryptionKey: encryptionKey },
+      // :emphasize-end:
+    };
+    const app = new Realm.App(config);
+    // :snippet-end:
+
+    expect(app).toBeInstanceOf(Realm.App);
+  });
+
+  test("encrypting a realm", async () => {
+    const taskId = new BSON.ObjectId();
+    // :snippet-start: encrypt-realm
+    // Retrieve encryption key from secure location or create one
+    const encryptionKey = new ArrayBuffer(64);
+
+    // Use encryption key in realm configuration
+    const config = {
+      schema: [Task],
+      encryptionKey: encryptionKey, // :emphasize:
+    };
+
+    const realm = await Realm.open(config);
+    // :snippet-end:
+    expect(realm.isClosed).toBeFalsy;
+
+    realm.write(() => {
+      realm.create(Task, {
+        _id: taskId,
+        name: "Sweep the floor",
+      });
+    });
+
+    const Tasks = realm.objects(Task);
+    expect(Tasks.length).toBeGreaterThan(0);
+
+    realm.close();
+
+    // Reopen realm with key
+    const openRealmAgain = await Realm.open({
+      schema: [Task],
+      encryptionKey: encryptionKey,
+    });
+
+    const existingTask = openRealmAgain.objectForPrimaryKey(Task, taskId);
+    expect(existingTask).toBeTruthy;
+    expect(existingTask?._id).toEqual(taskId);
+  });
+});

examples/node/v12/__tests__/metadata.test.ts

@@ -0,0 +1,69 @@
+// :snippet-start: imports
+import Realm, {
+  AppConfiguration,
+  BSON,
+  MetadataMode,
+  Configuration,
+} from "realm";
+// :snippet-end:
+import { Task } from "./models/models";
+import { APP_ID } from "../config";
+
+describe("Handle Realm Metadata", () => {
+  test("encrypting realm metadata", () => {
+    // :snippet-start: encrypt-metadata
+    // Retrieve encryption key from secure location or create one
+    const encryptionKey = new ArrayBuffer(64);
+
+    // Use encryption key in app configuration
+    const config: AppConfiguration = {
+      id: APP_ID,
+      // :emphasize-start:
+      metadata: { mode: MetadataMode.Encryption, encryptionKey: encryptionKey },
+      // :emphasize-end:
+    };
+    const app = new Realm.App(config);
+    // :snippet-end:
+
+    expect(app).toBeInstanceOf(Realm.App);
+  });
+
+  test("encrypting a realm", async () => {
+    const taskId = new BSON.ObjectId();
+    // :snippet-start: encrypt-realm
+    // Retrieve encryption key from secure location or create one
+    const encryptionKey = new ArrayBuffer(64);
+
+    // Use encryption key in realm configuration
+    const config: Configuration = {
+      schema: [Task],
+      encryptionKey: encryptionKey, // :emphasize:
+    };
+
+    const realm = await Realm.open(config);
+    // :snippet-end:
+    expect(realm.isClosed).toBeFalsy;
+
+    realm.write(() => {
+      realm.create(Task, {
+        _id: taskId,
+        name: "Sweep the floor",
+      });
+    });
+
+    const Tasks = realm.objects(Task);
+    expect(Tasks.length).toBeGreaterThan(0);
+
+    realm.close();
+
+    // Reopen realm with key
+    const openRealmAgain = await Realm.open({
+      schema: [Task],
+      encryptionKey: encryptionKey,
+    });
+
+    const existingTask = openRealmAgain.objectForPrimaryKey(Task, taskId);
+    expect(existingTask).toBeTruthy;
+    expect(existingTask?._id).toEqual(taskId);
+  });
+});

examples/node/v12/__tests__/models/models.ts

@@ -0,0 +1,23 @@
+import Realm, { BSON, ObjectSchema } from "realm";
+
+export class Task extends Realm.Object<Task> {
+  _id!: BSON.ObjectId;
+  name!: String;
+  status?: String;
+  progressMinutes?: Number;
+  owner?: String;
+  dueDate?: Date;
+
+  static schema: ObjectSchema = {
+    name: "Task",
+    properties: {
+      _id: "objectId",
+      name: "string",
+      status: "string?",
+      progressMinutes: "int?",
+      owner: "string?",
+      dueDate: "date?",
+    },
+    primaryKey: "_id",
+  };
+}

examples/node/v12/package.json

@@ -15,7 +15,7 @@
   "license": "ISC",
   "dependencies": {
     "fs-extra": "^11.1.1",
-    "realm": "^12.1.0"
+    "realm": "^12.3.0"
   },
   "devDependencies": {
     "@babel/core": "^7.21.8",

examples/react-native/v12/TestApp/App.tsx

@@ -12,6 +12,7 @@ import {Logger} from './src/components/logger/Logger';
 import {ObjectModels} from './src/components/object-models/ObjectModels';
 import {RelationshipExamples} from './src/components/relationships/RealmWrapper';
 import {CompensatingWriteErrorHandling} from './src/components/errors/CompensatingWriteWrapper';
+import {EncryptMetadata} from './src/components/encryption/EncryptMetadata';
 
 // Screens
 import {SubscriptionScreen} from './src/screens/SubscriptionScreen';
@@ -22,6 +23,9 @@ import {RootStackParamList} from './src/navigation/types';
 
 const Drawer = createDrawerNavigator<RootStackParamList>();
 
+// Create encryption key for encryption examples.
+const encryptionKey = new ArrayBuffer(64);
+
 /* 
 // Each screen has its own RealmProvider and realm. However, they all point to
 // the default path. This means you'll get an error when you try to navigate
@@ -38,18 +42,46 @@ function App(): JSX.Element {
   return (
     <NavigationContainer>
       <Drawer.Navigator initialRouteName="Home">
-        <Drawer.Screen name="Home" component={HomeScreen} />
-        <Drawer.Screen name="Geospatial" component={Geospatial} />
-        <Drawer.Screen name="FullTextSearch" component={FtsQuery} />
-        <Drawer.Screen name="Logger" component={Logger} />
-        <Drawer.Screen name="ObjectModels" component={ObjectModels} />
-        <Drawer.Screen name="Subscriptions" component={SubscriptionScreen} />
-        <Drawer.Screen name="Relationships" component={RelationshipExamples} />
+        <Drawer.Screen
+          name="Home"
+          component={HomeScreen}
+        />
+        <Drawer.Screen
+          name="Geospatial"
+          component={Geospatial}
+        />
+        <Drawer.Screen
+          name="FullTextSearch"
+          component={FtsQuery}
+        />
+        <Drawer.Screen
+          name="Logger"
+          component={Logger}
+        />
+        <Drawer.Screen
+          name="ObjectModels"
+          component={ObjectModels}
+        />
+        <Drawer.Screen
+          name="Subscriptions"
+          component={SubscriptionScreen}
+        />
+        <Drawer.Screen
+          name="Relationships"
+          component={RelationshipExamples}
+        />
         <Drawer.Screen
           name="Errors"
           component={CompensatingWriteErrorHandling}
         />
-        <Drawer.Screen name="Authentication" component={AuthenticationScreen} />
+        <Drawer.Screen
+          name="Authentication"
+          component={AuthenticationScreen}
+        />
+        <Drawer.Screen
+          name="Encryption"
+          component={() => <EncryptMetadata encryptionKey={encryptionKey} />}
+        />
       </Drawer.Navigator>
     </NavigationContainer>
   );

examples/react-native/v12/TestApp/package.json

@@ -25,7 +25,7 @@
     "react-native-reanimated": "^3.4.2",
     "react-native-safe-area-context": "^4.7.1",
     "react-native-screens": "^3.24.0",
-    "realm": "^12.2.1"
+    "realm": "^12.2.3"
   },
   "devDependencies": {
     "@babel/core": "^7.20.0",

examples/react-native/v12/TestApp/src/components/encryption/EncryptMetadata.test.tsx

@@ -0,0 +1,16 @@
+import 'react-native';
+import React from 'react';
+import {render, screen} from '@testing-library/react-native';
+
+import {EncryptMetadata} from './EncryptMetadata';
+
+// Create encryption key for encryption examples.
+const encryptionKey = new ArrayBuffer(64);
+
+test('linking an anonymous user with an email/password account', async () => {
+  render(<EncryptMetadata encryptionKey={encryptionKey} />);
+
+  const encryptionResultTextNode = await screen.findByTestId('is-realm-app');
+  expect(encryptionResultTextNode).toBeInTheDocument;
+  expect(encryptionResultTextNode.children[1]).toBe('true');
+});

examples/react-native/v12/TestApp/src/components/encryption/EncryptMetadata.tsx

@@ -0,0 +1,59 @@
+// :snippet-start: imports
+import React from 'react';
+import {Text, View} from 'react-native';
+import {MetadataMode} from 'realm';
+import {AppProvider} from '@realm/react';
+// :snippet-end:
+import {StyleSheet} from 'react-native';
+import {useApp} from '@realm/react';
+import {APP_ID} from '../../../appServicesConfig';
+
+// :snippet-start: encrypt-metadata
+// :replace-start: {
+//    "terms": {
+//       "export ": ""
+//    }
+// }
+export const EncryptMetadata = ({
+  encryptionKey,
+}: {
+  encryptionKey: ArrayBuffer;
+}) => {
+  const metadataConfig = {
+    // :emphasize-start:
+    mode: MetadataMode.Encryption,
+    encryptionKey: encryptionKey,
+    // :emphasize-end:
+  };
+
+  return (
+    <AppProvider
+      id={APP_ID}
+      metadata={metadataConfig}>
+      <RestOfApp />
+    </AppProvider>
+  );
+};
+// :replace-end:
+// :snippet-end:
+
+const RestOfApp = () => {
+  const app = useApp();
+
+  return (
+    <View style={styles.section}>
+      <Text testID="is-realm-app">
+        Is an instance of `Realm.App`?: {app ? 'true' : 'false'}
+      </Text>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  section: {
+    flex: 1,
+    marginTop: 8,
+    paddingVertical: 12,
+    alignItems: 'center',
+  },
+});