@superblocksteam/shared 0.9108.0

package/src/relay/types.ts

@@ -0,0 +1,11 @@
+export type RelayRules = (string | Record<string, string>)[];
+
+export interface Relay {
+  headers: RelayRules;
+  query: RelayRules;
+  body: RelayRules;
+}
+
+export const NO_RELAY: Relay = { headers: [], body: [], query: [] };
+
+export const RELAY_BODY_FIELD_NAME = 'relays';

package/src/signing/JSON/fast.ts

@@ -0,0 +1,20 @@
+// A replacer function to be used with JSON.stringify.
+// It sorts the keys of an object so that they are traversed by `JSON.stringify` in the canonical order.
+function replacer(_key: string, value: unknown): unknown {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return value;
+  }
+  // `value` is an object
+  const sortedObj = {};
+  Object.keys(value)
+    .sort()
+    .forEach((key) => {
+      sortedObj[key] = value[key];
+    });
+  return sortedObj;
+}
+
+// export so that it can be used in tests
+export function stableJSONStringify_fast(value: unknown): string | undefined {
+  return JSON.stringify(value, replacer);
+}

package/src/signing/JSON/index.test.ts

@@ -0,0 +1,99 @@
+import { stableJSONStringify_fast } from './fast';
+import { stableJSONStringify_portable } from './portable';
+import { stableJSONStringify, testStringOut, testStringSrc } from '.';
+
+// an object with keys that are intentionally out of order
+const obj1 = {
+  // some alphanumeric keys
+  b: 0,
+  a: 1,
+
+  // some keys that could be interpreted as indices
+  '1': 2,
+  '10': 3,
+  '7': 4,
+
+  // some keys that could be interpreted as numbers but not as indices
+  '2.0': 5,
+  '10.0': 6,
+  '+0': 7,
+  '-0': 8,
+
+  // a key that sorts before the numeric keys, but should appear after the indices
+  $c: 9,
+
+  // Symbol keys should be ignored
+  [Symbol('f')]: 10
+};
+
+const expectedObj1String = '{"1":2,"7":4,"10":3,"$c":9,"+0":7,"-0":8,"10.0":6,"2.0":5,"a":1,"b":0}';
+
+// a class with a toJSON method that returns an object
+class ClassWithToJSON {
+  toJSON() {
+    return obj1;
+  }
+}
+
+// an object with a property that is an instance of a class with a toJSON method
+const obj2 = {
+  a: new ClassWithToJSON()
+};
+
+const stableJSONStringify_implementations: Record<string, typeof stableJSONStringify> = {
+  stableJSONStringify_fast,
+  stableJSONStringify_portable
+};
+
+// an object with keys that should be ignored because of their value type
+const obj3 = {
+  a: undefined,
+  b: () => {
+    /* do nothing */
+  }
+};
+
+const complexObj = {
+  // deliberately out of order
+  obj3,
+  obj1,
+  obj2,
+  booleanKey: true
+};
+
+describe('stableJSONStringify', () => {
+  describe('object keys should be returned in canonical order', () => {
+    test.each(Object.entries(stableJSONStringify_implementations))('stableJSONStringify implementation: %s', (_name, stringify) => {
+      const str1 = stringify(obj1);
+      expect(str1).toEqual(expectedObj1String);
+
+      // verify that the canonicalization is applied recursively to objects returned by toJSON methods
+      const str2 = stringify(obj2);
+      expect(str2).toEqual('{"a":' + expectedObj1String + '}');
+    });
+  });
+
+  describe('some object properties should be skipped', () => {
+    test.each(Object.entries(stableJSONStringify_implementations))('stableJSONStringify implementation: %s', (_name, stringify) => {
+      expect(stringify(obj3)).toEqual('{}');
+    });
+  });
+
+  describe('skipped values are treated as null in arrays', () => {
+    test.each(Object.entries(stableJSONStringify_implementations))('stableJSONStringify implementation: %s', (_name, stringify) => {
+      const values = Object.values(obj3);
+      const expected = '[' + new Array(values.length).fill('null').join(',') + ']';
+      expect(stringify(values)).toEqual(expected);
+    });
+  });
+
+  describe('escaping of characters in strings is consistent', () => {
+    test.each(Object.entries(stableJSONStringify_implementations))('stableJSONStringify implementation: %s', (_name, stringify) => {
+      expect(stringify(testStringSrc)).toEqual(testStringOut);
+    });
+  });
+
+  test('the two implementations agree on a complex object', () => {
+    expect(stableJSONStringify_fast(complexObj)).toEqual(stableJSONStringify_portable(complexObj));
+  });
+});

package/src/signing/JSON/index.ts

@@ -0,0 +1,78 @@
+import { stableJSONStringify_fast } from './fast';
+import { stableJSONStringify_portable } from './portable';
+
+// For some signing operations, we need to be able to sign JSON objects in a deterministic and stable way.
+// `JSON.stringify` is not guaranteed to produce a stable output, so we provide our own implementation instead.
+
+// In general, there are several reasons why JSON serialization might not be stable:
+// * JSON allows insignificant whitespace to be inserted in various places.  `JSON.stringify` does not do that though.
+// * The keys in an object can be serialized in any order. `JSON.stringify` is not stable in that regard because it (mostly)
+//   respects the order in which the keys were added to the object (with the exception of keys that could be interpreted as
+//   indices, which are serialized in numeric order and before all keys).
+// * The characters in a string can be escaped in various ways. For example, the character `\n` can be represented as `\n` or
+//   as `\u000a` and the character `A` can be represented as `A` or as `\u0041`. The EcmaScript spec does not specify which
+//   representation `JSON.stringify` should use. It seems that `JSON.stringify` in modern browsers uses the shortest
+//   representation, but that is not guaranteed by the spec.
+// * Objects can provide a `toJSON` method that behaves in an arbitrary way.
+// * Numbers can be represented in various ways. For example, the number `0` can be represented as `0`, `-0`, `+0`, `0.0`, `-0.0`,
+
+// Our implementation of `stableJSONStringify` addresses most of these issues:
+// * It does not insert insignificant whitespace.
+// * It sorts the keys in an object in a canonical order defined below.
+// * It uses the shortest representation for each character in a string.
+// * It respects `toJSON` methods, but it cannot protect against `toJSON` implementations that behave in an arbitrary way. We assume
+//   that we will serialize only standard EcmaScript objects such as `Date` which have well-defined `toJSON` methods.
+// * It does not attempt to canonicalize numbers, we rely on the fact the `toJSON` method of numbers returns a string that uses the
+//   shortest representation.
+
+// Canonical order for object keys:
+// * Keys that could be interpreted as indices are sorted by numeric value and before all other keys. See `isIndexKey` for the definition.
+// * Other keys are sorted in lexicographic case-insensitive order, based on Unicode code points. See `compareObjectKeys` for the details.
+// The rationale for using this order instead of a lexicographical order on all keys is that it allows us to leverage
+// `JSON.stringify` to obtain a more performant implementation.
+
+// Shortest representation of characters in strings:
+// * We only escape the characters that need to be escaped according to RFC 8259. If a character has a two character escape sequence,
+//   we use that escape sequence. All other characters are represented as a numeric \uXXXX escape sequence. In those sequences, we
+//   always use lowercase hexadecimal digits.
+// * All other characters are represented as unescaped literal characters (i.e. they are represented as themselves).
+
+// We provide two implementations of `stableJSONStringify`:
+// * `stableJSONStringify_portable` is a portable but slower implementation.
+// * `stableJSONStringify_fast` is a faster implementation that partially relies on the native `JSON.stringify`. This implementation
+//   is not guaranteed to produce the same output as `stableJSONStringify_portable` under all JavaScript engines. Then reason for that is
+//   that `JSON.stringify` is not guaranteed to produce the shortest representation for strings,
+//   but it should do that under most modern JavaScript engines. So we only use this implementation after testing that it
+//   handles strings correctly. This should be the case under all modern JavaScript engines.
+
+// Some test strings that we use to test that the fast implementation produces the correct output
+// They are broken down into categories of characters
+const testStrings: { src: string; out: string }[] = [
+  {
+    // All C0 control characters: they should represented as \uXXXX numeric escapes, except for \b, \f, \n, \r, \t, which should be represented as \b, \f, \n, \r, \t
+    src: `\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f`,
+    out: `\\u0000\\u0001\\u0002\\u0003\\u0004\\u0005\\u0006\\u0007\\b\\t\\n\\u000b\\f\\r\\u000e\\u000f\\u0010\\u0011\\u0012\\u0013\\u0014\\u0015\\u0016\\u0017\\u0018\\u0019\\u001a\\u001b\\u001c\\u001d\\u001e\\u001f`
+  },
+  {
+    // All C1 control characters: they should be represented literally
+    src: `\x80\x81\x82\x83\x84\x85\x86\x87\x88\x89\x8a\x8b\x8c\x8d\x8e\x8f\x90\x91\x92\x93\x94\x95\x96\x97\x98\x99\x9a\x9b\x9c\x9d\x9e\x9f`,
+    out: `\x80\x81\x82\x83\x84\x85\x86\x87\x88\x89\x8a\x8b\x8c\x8d\x8e\x8f\x90\x91\x92\x93\x94\x95\x96\x97\x98\x99\x9a\x9b\x9c\x9d\x9e\x9f`
+  },
+  {
+    // Other characters: they should be represented literally. We test:
+    // * Some ASCII characters
+    // * Some non-ASCII characters in the Basic Multilingual Plane
+    // * Some characters outside the Basic Multilingual Plane
+    src: `aπ€ℤ🍔`,
+    out: `aπ€ℤ🍔`
+  }
+];
+
+// export so that it can be used in tests
+export const testStringSrc = testStrings.map((x) => x.src).join('');
+export const testStringOut = '"' + testStrings.map((x) => x.out).join('') + '"';
+
+// TODO: send a log event if the portable but slower implementation is used
+const canUseFast = stableJSONStringify_fast(testStringSrc) === testStringOut;
+
+export const stableJSONStringify = canUseFast ? stableJSONStringify_fast : stableJSONStringify_portable;

package/src/signing/JSON/portable.ts

@@ -0,0 +1,115 @@
+// RFC 8259 calls the following "two character sequence escape representations of some popular characters"
+const popularCharsEscapes = {
+  '\b': '\\b',
+  '\t': '\\t',
+  '\n': '\\n',
+  '\f': '\\f',
+  '\r': '\\r',
+  '"': '\\"',
+  '\\': '\\\\'
+};
+
+// Escape a single character to be used in a JSON string
+// We follow RFC 8259 suggestions and produce the shortest possible escape sequence:
+// * for "popular characters", we use the two character sequence escape representation
+// * for other characters, we use the \uXXXX numeric escape representation
+function escapeChar(char: string): string {
+  const popularEscape = popularCharsEscapes[char];
+  if (popularEscape !== undefined) {
+    // We found a "popular character", use the short two character escape sequence
+    return popularEscape;
+  } else {
+    // All other characters should be represented as a numeric \uXXXX escape
+
+    // We are in the Basic Multilingual Plane, so `.charCodeAt` will return the same value as `.codePointAt`
+    // We use `.charCodeAt` because it is faster
+    const codePoint = char.charCodeAt(0);
+    return '\\u' + codePoint.toString(16).padStart(4, '0');
+  }
+}
+
+// The set of characters that need to be escaped in a JSON string
+// We only escape the characters that need to be escaped according to RFC 8259
+// This consists of:
+// * C0 control characters (U+0000 through U+001F)
+// * quotation mark (U+0022) and reverse solidus (U+005C), which are special characters in JSON
+// * surrogate code points (U+D800 through U+DFFF), which should only match when unpaired, which is are actually invalid in unicode, but RFC 8259 suggests to escape them when they appear because of errors
+// We use the `u` flag to match surrogates only when they are unpaired
+// Note: this is one of the rare occasions where we do want control characters in a regex, so we disable the eslint rule
+// eslint-disable-next-line no-control-regex
+const charsToEscape = /[\u0000-\u001f\ud800-\udfff"\\]/gu;
+
+function JSONStringifyString(str: string) {
+  return `"` + str.replace(charsToEscape, escapeChar) + `"`;
+}
+
+function isIndexKey(key: string): boolean {
+  // EcmaScript defines an index key as a string that is a base-10 unsigned integer
+  // that does not have a leading zero or is '0'
+  return key === '0' || /^[1-9]\d*$/.test(key);
+}
+
+function compareObjectKeys(a: string, b: string): number {
+  const aIsIndexKey = isIndexKey(a);
+  const bIsIndexKey = isIndexKey(b);
+  // follow EcmaScript for sorting keys that could be interpreted as indices:
+  // sort keys that could be interpreted as indices before other keys
+  // these keys are sorted by numeric value
+  return aIsIndexKey && bIsIndexKey ? Math.sign(Number(a) - Number(b)) : aIsIndexKey ? -1 : bIsIndexKey ? 1 : a < b ? -1 : a > b ? 1 : 0;
+}
+
+// adapted from https://github.com/epoberezkin/fast-json-stable-stringify
+// export so that it can be used in tests
+export function stableJSONStringify_portable(data: unknown): string | undefined {
+  // track the objects being serialized, so that we don't get into an infinite cycle
+  const seen = new Set<unknown>();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (function stringify(node: any) {
+    if (typeof node?.toJSON === 'function') {
+      node = node.toJSON();
+    }
+
+    if (typeof node == 'number') return isFinite(node) ? '' + node : 'null';
+
+    if (typeof node === 'string') return JSONStringifyString(node);
+
+    if (typeof node === 'boolean') return `${node}`;
+
+    if (node === null) return 'null';
+
+    if (typeof node === 'object') {
+      if (seen.has(node)) {
+        throw new TypeError('Converting circular structure to JSON');
+      }
+      seen.add(node);
+
+      if (Array.isArray(node)) {
+        let out = '[';
+        for (let idx = 0; idx < node.length; idx++) {
+          if (idx > 0) out += ',';
+          out += stringify(node[idx]) ?? 'null';
+        }
+        seen.delete(node);
+        return out + ']';
+      } else {
+        const keys = Object.keys(node).sort(compareObjectKeys);
+        let out = '';
+        for (const key of keys) {
+          const value = stringify(node[key]);
+          if (!value) continue;
+          if (out) out += ',';
+          out += JSONStringifyString(key) + ':' + value;
+        }
+        seen.delete(node);
+        return '{' + out + '}';
+      }
+    }
+
+    if (typeof node === 'bigint') {
+      // The ECMAScript JSON.stringify function cannot serialize BigInts
+      throw new TypeError('Do not know how to serialize a BigInt');
+    }
+
+    if (node === undefined || typeof node === 'function') return;
+  })(data);
+}

package/src/signing/constants.ts

@@ -0,0 +1,95 @@
+import { Api as ApiPb } from '@superblocksteam/types';
+import { AnyPageDSL, ApplicationConfiguration, ApplicationSettings } from '../types';
+
+/** A signature, as produced by the agent. */
+export interface Signature {
+  /** The id of the key used to sign the data. */
+  keyId: string;
+  /** The actual signature, in base64. */
+  data: string;
+  /** The public key for the key used to sign the data, in base64. */
+  publicKey?: string;
+  /** The algorithm used to sign the data. */
+  algorithm?: string;
+}
+
+interface VersionedDslHash {
+  /** The version of the DSL. */
+  version: number;
+  /**
+   * The SHA-256 hash of the DSL, in base64.
+   * For pages, this is the hash of the actual page DSL, i.e. `page.layouts[0].dsl`.
+   * */
+  hash: string;
+}
+
+export interface ApplicationSettingsHashes {
+  /** The SHA-256 hash of all custom components related properties from settings, in base64. */
+  components: string;
+  /** The SHA-256 hash of settings without the custom components related properties, in base64. */
+  rest: string;
+}
+
+export interface ApplicationSignatureTreeV1 {
+  /** The version of the signature tree. */
+  v: 1;
+  settings: ApplicationSettingsHashes;
+  page: VersionedDslHash;
+}
+
+export interface ApplicationSignatureTreeV2 {
+  /** The version of the signature tree. */
+  v: 2;
+  settings: ApplicationSettingsHashes;
+  pages: Record<string, VersionedDslHash>;
+  configuration: VersionedDslHash;
+}
+
+export type ApplicationSignatureTree = ApplicationSignatureTreeV1 | ApplicationSignatureTreeV2;
+
+export interface ApplicationSignatureTreeSigned {
+  /** The SHA-256 hash of `root`, in base64. */
+  signature: Signature;
+  root: ApplicationSignatureTree;
+}
+
+export type PageUpdate = {
+  type: 'page';
+  pageId: string;
+  pageDsl: AnyPageDSL;
+};
+
+export type PageDelete = {
+  type: 'delete-page';
+  pageId: string;
+};
+
+export type ConfigurationUpdate = {
+  type: 'configuration';
+  configuration: ApplicationConfiguration;
+};
+
+export type SettingUpdate = {
+  type: 'settings';
+  settings: ApplicationSettings;
+};
+
+export type ApplicationSignatureTreeUpdate = PageUpdate | PageDelete | ConfigurationUpdate | SettingUpdate;
+
+export type AppToSign = {
+  rootHash: string;
+};
+
+export type AppToVerify = {
+  rootHash: string;
+  signature?: Signature;
+};
+
+export type ApiToSign = {
+  apiPb: ApiPb;
+};
+
+export type ApiToVerify = {
+  apiPb: ApiPb;
+  signature?: Signature;
+};

package/src/signing/hashing.test.ts

@@ -0,0 +1,77 @@
+import { sha256Base64 } from './hashing';
+
+describe('hashing', () => {
+  describe('sha256Base64', () => {
+    const testString = 'This is a test';
+    const expectedHash = 'x74e2QL7jdTUiZfGRS9dflCfvNvigIsWvPTtzkwH0U4=';
+
+    it('hashes a string correctly', async () => {
+      const hash = await sha256Base64(testString);
+      expect(hash).toEqual(expectedHash);
+    });
+
+    it('hashes a node.js buffer correctly', async () => {
+      const buffer = Buffer.from(testString);
+      const hash = await sha256Base64(buffer);
+      expect(hash).toEqual(expectedHash);
+    });
+
+    it('hashes a Uint8Array correctly', async () => {
+      const uint8Array = new TextEncoder().encode(testString);
+      const hash = await sha256Base64(uint8Array);
+      expect(hash).toEqual(expectedHash);
+    });
+
+    it('hashes a Uint16Array correctly', async () => {
+      const uint8Array = new TextEncoder().encode(testString);
+
+      // before we convert (the underlying buffer) to a Uint16Array, we need to make sure that the length is a multiple of 2
+      expect(uint8Array.length % 2).toEqual(0);
+
+      // create a new Uint16Array that is a view into the same underlying buffer
+      const uint16Array = new Uint16Array(uint8Array.buffer, uint8Array.byteOffset, uint8Array.length / 2);
+
+      const hash = await sha256Base64(uint16Array);
+      expect(hash).toEqual(expectedHash);
+    });
+
+    it('hashes an ArrayBuffer correctly', async () => {
+      const uint8Array = new TextEncoder().encode(testString);
+      // Create a new array buffer that is the same length as the uint8Array.  We don't use the underlying buffer
+      // of the uint8Array because it might be longer. Instead, we create a new array buffer that is the same length.
+      const arrayBuffer = new ArrayBuffer(uint8Array.length);
+
+      // copy the uint8Array into the arrayBuffer
+      const arrayBufferView = new Uint8Array(arrayBuffer);
+      arrayBufferView.set(uint8Array);
+
+      const hash = await sha256Base64(arrayBuffer);
+      expect(hash).toEqual(expectedHash);
+
+      // also test the view
+      const hashView = await sha256Base64(arrayBufferView);
+      expect(hashView).toEqual(expectedHash);
+    });
+
+    it('hashes a Uint8Array correctly, even when the underlying buffer is longer', async () => {
+      const uint8Array = new TextEncoder().encode(testString);
+
+      // Create a new array buffer that is longer than the uint8Array.
+      const arrayBuffer = new ArrayBuffer(uint8Array.length + 2);
+
+      // Copy the uint8Array into the arrayBuffer, starting at index 1. Set the first and last bytes to some fixed values.
+      const arrayBufferView = new Uint8Array(arrayBuffer);
+      arrayBufferView[0] = 1;
+      arrayBufferView[arrayBufferView.length - 1] = 2;
+      arrayBufferView.set(uint8Array, 1);
+
+      // Create a new uint8Array that has the same content as the uint8Array, but has an underlying buffer that is longer.
+      const uint8ArraySlice = new Uint8Array(arrayBuffer, 1, uint8Array.length);
+      // Verify that the underlying buffer of the uint8ArraySlice is referencially the same as `arrayBuffer`.
+      expect(uint8ArraySlice.buffer).toEqual(arrayBuffer);
+
+      const hash = await sha256Base64(uint8ArraySlice);
+      expect(hash).toEqual(expectedHash);
+    });
+  });
+});

package/src/signing/hashing.ts

@@ -0,0 +1,47 @@
+import { Base64 } from 'js-base64';
+
+// This module is used by the FE and the BE, so it must be compatible with both.
+// For both sides, we are using the Web Crypto API. This API is supported by all modern browsers, and
+// newer versions of Node.js.
+
+const isNodeJS = typeof globalThis.process?.versions?.node !== 'undefined';
+
+// The Web Crypto API entry point
+let crypto = globalThis.crypto;
+
+// TODO(george): remove this function once we do not need support for Node.js 15-19
+async function ensureWebCryptoApiIsLoaded() {
+  if (isNodeJS) {
+    const nodeJsCrypto = await import(/* webpackIgnore: true */ 'crypto');
+    crypto = nodeJsCrypto.webcrypto as unknown as Crypto;
+  }
+  if (!crypto) {
+    throw new Error('Web Crypto API is not available');
+  }
+}
+
+/**
+ * Returns the SHA-256 hash of the given message.
+ * @param message The message to hash, that could be a string or a binary. If a string is given, it will be encoded as UTF-8.
+ * @returns The raw SHA-256 hash of the given message in binary form.
+ */
+export async function sha256(message: string | BufferSource): Promise<ArrayBuffer> {
+  await ensureWebCryptoApiIsLoaded();
+  // If the message is a string, we need convert it to a Uint8Array because the Web Crypto API does not support strings.
+  // Otherwise, we can pass the message directly to the Web Crypto API.
+  if (typeof message === 'string') {
+    // Note: `TextEncoder` always encodes as UTF-8.
+    message = new TextEncoder().encode(message);
+  }
+  return await crypto.subtle.digest('SHA-256', message);
+}
+
+/**
+ * Returns the SHA-256 hash of the given message, encoded as a base64 string.
+ * @param message The message to hash, that could be a string or a binary. If a string is given, it will be encoded as UTF-8.
+ * @returns The SHA-256 hash of the given message, encoded as a base64 string.
+ */
+export async function sha256Base64(message: string | BufferSource): Promise<string> {
+  const rawHash = await sha256(message);
+  return Base64.fromUint8Array(new Uint8Array(rawHash));
+}

package/src/signing/index.test.ts

@@ -0,0 +1,116 @@
+import { UtilsV1 as UtilsV1Pb } from '@superblocksteam/types';
+import { AnyPageDSL, ApplicationConfiguration, ApplicationSettings } from '../types';
+import {
+  ApplicationSignatureTreeV1,
+  ApplicationSignatureTreeV2,
+  createApplicationSignatureTree,
+  getAlgorithmName,
+  verifyApplicationHashTree
+} from './index';
+
+const pageDsl = {
+  version: 8,
+  widgetId: '0',
+  children: []
+} as unknown as AnyPageDSL;
+const appSettings = {} as ApplicationSettings;
+const appConfiguration = {
+  routes: {}
+} as ApplicationConfiguration;
+const hashTreeV1: ApplicationSignatureTreeV1 = {
+  v: 1,
+  page: {
+    hash: 'ZMpaDRZaIl1QxyEwrjoPUQJbkcCtTsNXbVySIGlcgVg=',
+    version: 8
+  },
+  settings: {
+    components: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
+    rest: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o='
+  }
+};
+const hashTreeV2: ApplicationSignatureTreeV2 = {
+  v: 2,
+  pages: {
+    'fake-page-id': {
+      hash: 'ZMpaDRZaIl1QxyEwrjoPUQJbkcCtTsNXbVySIGlcgVg=',
+      version: 8
+    }
+  },
+  settings: {
+    components: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
+    rest: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o='
+  },
+  configuration: {
+    version: 1,
+    hash: 'boT9TuU6iU3HiVIO8vh8YU+SgXAozIHLSuhRcux09F8='
+  }
+};
+
+describe('createApplicationSignatureTree', () => {
+  it('returns a v2 signature tree', async () => {
+    const calculatedHashTree = await createApplicationSignatureTree({
+      pages: { 'fake-page-id': pageDsl },
+      appSettings,
+      configuration: appConfiguration
+    });
+    expect(calculatedHashTree).toEqual(hashTreeV2);
+  });
+});
+
+describe('verifyApplicationHashTree', () => {
+  describe('v1', () => {
+    it('verifies a v1 signature tree', async () => {
+      const result = await verifyApplicationHashTree({ hashTree: hashTreeV1, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(true);
+    });
+
+    it('returns false if the page hash does not match', async () => {
+      const badHashTree = { ...hashTreeV1, page: { ...hashTreeV1.page, hash: 'bad-hash' } };
+      const result = await verifyApplicationHashTree({ hashTree: badHashTree, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(false);
+    });
+
+    it('returns false if the settings hash does not match', async () => {
+      const badHashTree = { ...hashTreeV1, settings: { ...hashTreeV1.settings, components: 'bad-hash' } };
+      const result = await verifyApplicationHashTree({ hashTree: badHashTree, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('v2', () => {
+    it('verifies a v2 signature tree', async () => {
+      const result = await verifyApplicationHashTree({ hashTree: hashTreeV2, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(true);
+    });
+
+    it('returns false if the page hash does not match', async () => {
+      const badHashTree = { ...hashTreeV2, pages: { 'fake-page-id': { ...hashTreeV2.pages['fake-page-id'], hash: 'bad-hash' } } };
+      const result = await verifyApplicationHashTree({ hashTree: badHashTree, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(false);
+    });
+
+    it('returns false if the settings hash does not match', async () => {
+      const badHashTree = { ...hashTreeV2, settings: { ...hashTreeV2.settings, components: 'bad-hash' } };
+      const result = await verifyApplicationHashTree({ hashTree: badHashTree, pages: { 'fake-page-id': pageDsl }, appSettings });
+      expect(result).toBe(false);
+    });
+  });
+});
+
+describe('get algorithm name', () => {
+  it.each([
+    {
+      name: 'unspecified algorithm',
+      algorithm: UtilsV1Pb.Signature_Algorithm.UNSPECIFIED,
+      expected: 'ALGORITHM_UNSPECIFIED'
+    },
+    {
+      name: 'ED25519 algorithm',
+      algorithm: UtilsV1Pb.Signature_Algorithm.ED25519,
+      expected: 'ALGORITHM_ED25519'
+    }
+  ])('should return $expected for $name', ({ algorithm, expected }) => {
+    const actual = getAlgorithmName(algorithm);
+    expect(actual).toEqual(expected);
+  });
+});