(DOCSP-33626) Document metadata encryption

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/babel.config.cjs

@@ -1,7 +1,7 @@
 module.exports = {
   presets: [
     ['@babel/preset-env', {targets: {node: 'current'}}],
-    // 'module:metro-react-native-babel-preset',
+    'module:metro-react-native-babel-preset',
     '@babel/preset-typescript',
   ],
   plugins: ['react-native-reanimated/plugin'],

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');
+});