encoding: Expand on the context of our new base64Utf8Encode.

Also make the tests more informative -- 'W29iamVjdCBPYmplY3Rd' turns
out to be the base64-encoding of the string '[object Object]'. :-)

Author: gnprice

src/utils/__tests__/encoding-test.js

@@ -5,7 +5,7 @@ import {
   hexToAscii,
   asciiToHex,
   xorHexStrings,
-  strToBase64,
+  base64Utf8Encode,
   extractApiKey,
 } from '../encoding';
 
@@ -62,33 +62,18 @@ describe('asciiToHex', () => {
   });
 });
 
-describe('strToBase64', () => {
+describe('base64Utf8Encode', () => {
   test('can handle an empty string', () => {
-    const obj = '';
+    const text = '';
     const expected = '';
-
-    const result = strToBase64(obj);
-
-    expect(result).toBe(expected);
-  });
-
-  test('can encode any string', () => {
-    const obj = {
-      key: 'ABCabc123',
-      empty: null,
-      array: [1, 2, 3],
-    };
-    const expected = 'W29iamVjdCBPYmplY3Rd';
-
-    const result = strToBase64(obj);
-
+    const result = base64Utf8Encode(text);
     expect(result).toBe(expected);
   });
 
-  test('supports unicode characters', () => {
-    const obj = { key: '😇😈' };
-    const expected = 'W29iamVjdCBPYmplY3Rd';
-    const result = strToBase64(obj);
+  test('supports Unicode characters outside the BMP', () => {
+    const text = '😇😈';
+    const expected = '8J+Yh/CfmIg=';
+    const result = base64Utf8Encode(text);
     expect(result).toBe(expected);
   });
 });

src/utils/encoding.js

@@ -32,11 +32,26 @@ export const base64ToHex = (bytes: string) => asciiToHex(base64.decode(bytes));
 
 export const hexToBase64 = (hex: string) => base64.encode(hexToAscii(hex));
 
-/** Encode a JavaScript string to a string in Base64 format. */
-export const strToBase64 = (text: string): string =>
+/**
+ * Encode a string as the base64 representation of its UTF-8 bytes.
+ *
+ * This lets us pass an arbitrary string through a channel (like the
+ * `postMessage` on RN's webviews on Android) that tries to do something
+ * like percent-decode it.
+ */
+export const base64Utf8Encode = (text: string): string =>
   // References on reliably encoding strings to Base64:
   // https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa#Unicode_strings
   // https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding
+  //
+  // In short:
+  //  * base64 encoders want bytes, not really Unicode strings, so they
+  //    insist their input consist of the characters U+0000 to U+00FF;
+  //  * `encodeURIComponent` together with `unescape` is a way of getting
+  //    that, effectively producing the UTF-8 encoding of the input.
+  //
+  // We use `base64.encode` because `btoa` is unavailable in the JS
+  // environment provided by RN on iOS.
   base64.encode(unescape(encodeURIComponent(text)));
 
 // Extract an API key encoded as a hex string XOR'ed with a one time pad (OTP)