feat(hierarchical-keyring): Uuidv4 byte compression (#626)

* wrote code and added tests from MPL

* explain the ranges

Author: nvobilis

modules/serialize/src/index.ts

@@ -12,3 +12,4 @@ export * from './identifiers'
 export * from './uint_util'
 export * from './signature_info'
 export * from './ecdsa_signature'
+export * from './uuidv4_factory'

modules/serialize/src/uuidv4_factory.ts

@@ -0,0 +1,68 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { needs } from '@aws-crypto/material-management'
+import { validate, version } from 'uuid'
+
+// function to validate a string as uuidv4
+const validateUuidv4 = (input: string): boolean =>
+  validate(input) && version(input) === 4
+
+// accepts user defined lambda functions to convert between a string and
+// compressed hex encoded
+// bytes. This factory is a higher order function that returns the compression
+// and decompression functions based on the input lambda functions
+export function uuidv4Factory(
+  stringToHexBytes: (input: string) => Uint8Array,
+  hexBytesToString: (input: Uint8Array) => string
+) {
+  return { uuidv4ToCompressedBytes, decompressBytesToUuidv4 }
+
+  // remove the '-' chars from the uuid string and convert to hex bytes
+  function uuidv4ToCompressedBytes(uuidString: string): Uint8Array {
+    /* Precondition: Input string must be valid uuidv4 */
+    needs(validateUuidv4(uuidString), 'Input must be valid uuidv4')
+
+    const uuidBytes = new Uint8Array(
+      stringToHexBytes(uuidString.replace(/-/g, ''))
+    )
+
+    /* Postcondition: Compressed bytes must have correct byte length */
+    needs(
+      uuidBytes.length === 16,
+      'Unable to convert uuid into compressed bytes'
+    )
+
+    return uuidBytes
+  }
+
+  // convert the hex bytes to a string. Reconstruct the uuidv4 string with the
+  // '-' chars
+  function decompressBytesToUuidv4(uuidBytes: Uint8Array): string {
+    /* Precondition: Compressed bytes must have correct byte length */
+    needs(uuidBytes.length === 16, 'Compressed uuid has incorrect byte length')
+
+    const hex = hexBytesToString(uuidBytes)
+    let uuidString: string
+
+    try {
+      // These represent the ranges of the uuidv4 string that contain
+      // alphanumeric chars. We want to rebuild the proper uuidv4 string by
+      // joining these segments with the '-' char
+      uuidString = [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+      ].join('-')
+    } catch {
+      throw new Error('Unable to decompress UUID compressed bytes')
+    }
+
+    /* Postcondition: Output string must be valid uuidv4  */
+    needs(validateUuidv4(uuidString), 'Input must represent a uuidv4')
+
+    return uuidString
+  }
+}

modules/serialize/test/uuidv4_factory.test.ts

@@ -0,0 +1,114 @@
+// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// tests contains MPL tests: https://github.com/aws/aws-cryptographic-material-providers-library/blob/da6812fa30315fda75d4277f814d1d0e36e22498/StandardLibrary/test/UUID.dfy
+
+import { v3, v5, v1, v4 } from 'uuid'
+import { uuidv4Factory } from '../src/uuidv4_factory'
+import { expect } from 'chai'
+
+const stringToHexBytes = (input: string): Uint8Array =>
+  new Uint8Array(Buffer.from(input, 'hex'))
+
+const hexBytesToString = (input: Uint8Array): string =>
+  Buffer.from(input).toString('hex')
+
+const { uuidv4ToCompressedBytes, decompressBytesToUuidv4 } = uuidv4Factory(
+  stringToHexBytes,
+  hexBytesToString
+)
+
+const uuidString = '92382658-b7a0-4d97-9c49-cee4e672a3b3'
+const byteUuid = new Uint8Array([
+  146, 56, 38, 88, 183, 160, 77, 151, 156, 73, 206, 228, 230, 114, 163, 179,
+])
+const wrongByteUuid = new Uint8Array([
+  146, 56, 38, 88, 183, 160, 77, 151, 156, 73, 206, 228, 230, 114, 163, 178,
+])
+
+describe('uuidv4Factory', () => {
+  it('Test roundtrip string conversion', () => {
+    const stringToBytes = uuidv4ToCompressedBytes(uuidString)
+    expect(stringToBytes).has.lengthOf(16)
+    const bytesToString = decompressBytesToUuidv4(stringToBytes)
+    expect(bytesToString).to.equal(uuidString)
+  })
+
+  it('Test roundtrip byte conversion', () => {
+    const bytesToString = decompressBytesToUuidv4(byteUuid)
+    const stringToBytes = uuidv4ToCompressedBytes(bytesToString)
+    expect(stringToBytes).has.lengthOf(16)
+    expect(stringToBytes).to.deep.equal(byteUuid)
+  })
+
+  it('Test generate and conversion', () => {
+    const uuid = v4()
+    const uuidBytes = uuidv4ToCompressedBytes(uuid)
+    const bytesToString = decompressBytesToUuidv4(uuidBytes)
+    const stringToBytes = uuidv4ToCompressedBytes(bytesToString)
+
+    expect(stringToBytes).has.lengthOf(16)
+    expect(stringToBytes).to.deep.equal(uuidBytes)
+
+    const uuidStringToBytes = uuidv4ToCompressedBytes(uuid)
+    expect(uuidStringToBytes).has.lengthOf(16)
+    const uuidBytesToString = decompressBytesToUuidv4(uuidStringToBytes)
+    expect(uuidBytesToString).to.equal(uuid)
+  })
+
+  describe('decompressBytesToUuidv4', () => {
+    it('Precondition: Compressed bytes must have correct byte length', () => {
+      expect(() => decompressBytesToUuidv4(new Uint8Array([0]))).to.throw(
+        'Compressed uuid has incorrect byte length'
+      )
+    })
+
+    it('Postcondition: Output string must be valid uuidv4', () => {
+      expect(() =>
+        decompressBytesToUuidv4(new Uint8Array(Buffer.alloc(16)))
+      ).to.throw('Input must represent a uuidv4')
+    })
+
+    it('Test success', () => {
+      const fromBytes = decompressBytesToUuidv4(byteUuid)
+      expect(fromBytes).to.equal(uuidString)
+    })
+
+    it('Test failure', () => {
+      const fromBytes = decompressBytesToUuidv4(wrongByteUuid)
+      expect(fromBytes).to.not.equals(uuidString)
+    })
+  })
+
+  describe('uuidv4ToCompressedBytes', () => {
+    it('Precondition: Input string must be valid uuidv4', () => {
+      expect(() => uuidv4ToCompressedBytes(v1())).to.throw(
+        'Input must be valid uuidv4'
+      )
+
+      const name = 'example.com'
+      const namespace = uuidString
+      expect(() => uuidv4ToCompressedBytes(v3(name, namespace))).to.throw(
+        'Input must be valid uuidv4'
+      )
+
+      expect(() => uuidv4ToCompressedBytes(v5(name, namespace))).to.throw(
+        'Input must be valid uuidv4'
+      )
+    })
+
+    it('Postcondition: Compressed bytes must have correct byte length', () => {
+      expect(() => uuidv4ToCompressedBytes(uuidString)).to.not.throw()
+    })
+
+    it('Test success', () => {
+      const fromBytes = uuidv4ToCompressedBytes(uuidString)
+      expect(fromBytes).to.deep.equal(byteUuid)
+    })
+
+    it('Test failure', () => {
+      const fromBytes = uuidv4ToCompressedBytes(uuidString)
+      expect(fromBytes).to.not.deep.equals(wrongByteUuid)
+    })
+  })
+})