@ukeyfe/hardware-transport 1.1.13

package/.eslintrc

@@ -0,0 +1,24 @@
+{
+  "rules": {
+      "no-console": "off",
+      "@typescript-eslint/no-non-null-assertion": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/ban-ts-ignore": "off",
+      // We need empty functions for mocking modules for react-native
+      "@typescript-eslint/no-empty-function": "off",
+      "no-useless-constructor": "off",
+      "@typescript-eslint/no-useless-constructor": "error",
+      // valid case of class method overloads in typescript
+      "no-dupe-class-members": "off",
+      "@typescript-eslint/ban-ts-comment": "off",
+      //  Missing return type on function
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+      // note you must disable the base rule as it can report incorrect errors
+      "no-use-before-define": "off",
+      "@typescript-eslint/no-use-before-define": ["error"],
+      "@typescript-eslint/no-var-requires": "off",
+      "require-await": ["error"],
+      "import/no-named-default": "off",
+      "@typescript-eslint/ban-types": "off"
+  }
+}

package/README.md

@@ -0,0 +1,29 @@
+# `@ukeyfe/hardware-transport`
+
+`@ukeyfe/hardware-transport` is a library for low-level communication with UKey Hardware.
+
+## What is the purpose
+
+- translate JSON payloads to binary messages using protobuf definitions comprehensible to UKey devices
+- chunking and reading chunked messages according to the [UKey protocol](./protocol.md)
+- exposing single API for various transport methods:
+  - Http Transport
+  - React Native Transport
+  - WebUSB
+- Create and expose typescript definitions based on protobuf definitions.
+
+### The short version
+
+In order to be able to use new features of ukey-firmware you need to update protobuf definitions.
+
+1. `git submodule update --init --recursive` to initialize git submodules.
+1. `yarn update-submodules` to update firmware submodule
+1. `yarn update:protobuf` to generate new `./messages.json` and `./src/types/messages.ts`
+
+git submodule update --init --recursive to initialize firmware submodule
+yarn update-submodules to update firmware submodule
+yarn update:protobuf to generate new ./messages.json and ./src/types/messages.ts
+
+## Docs
+
+Documentation is available [hardware-js-sdk](https://developer.ukey.so/connect-to-hardware/hardware-sdk/start)

package/__tests__/build-receive.test.js

@@ -0,0 +1,117 @@
+const { parseConfigure } = require('../src/serialization/protobuf/messages');
+const { buildOne } = require('../src/serialization/send');
+const { receiveOne } = require('../src/serialization/receive');
+
+const { buildEncodeBuffers } = require('../src/serialization/send');
+
+const messages = {
+  StellarPaymentOp: {
+    fields: {
+      source_account: {
+        type: 'string',
+        id: 1,
+      },
+      destination_account: {
+        rule: 'required',
+        type: 'string',
+        id: 2,
+      },
+      asset: {
+        rule: 'required',
+        type: 'StellarAsset',
+        id: 3,
+      },
+      amount: {
+        rule: 'required',
+        type: 'sint64',
+        id: 4,
+      },
+    },
+  },
+  StellarAssetType: {
+    values: {
+      NATIVE: 0,
+      ALPHANUM4: 1,
+      ALPHANUM12: 2,
+    },
+  },
+  StellarAsset: {
+    fields: {
+      type: {
+        rule: 'required',
+        type: 'StellarAssetType',
+        id: 1,
+      },
+      code: {
+        type: 'string',
+        id: 2,
+      },
+      issuer: {
+        type: 'string',
+        id: 3,
+      },
+    },
+  },
+  MessageType: {
+    values: {
+      MessageType_StellarSignTx: 202,
+      MessageType_StellarTxOpRequest: 203,
+      MessageType_StellarGetAddress: 207,
+      MessageType_StellarAddress: 208,
+      MessageType_StellarCreateAccountOp: 210,
+      MessageType_StellarPaymentOp: 211,
+      MessageType_StellarPathPaymentOp: 212,
+      MessageType_StellarManageOfferOp: 213,
+      MessageType_StellarCreatePassiveOfferOp: 214,
+      MessageType_StellarSetOptionsOp: 215,
+      MessageType_StellarChangeTrustOp: 216,
+      MessageType_StellarAllowTrustOp: 217,
+      MessageType_StellarAccountMergeOp: 218,
+      MessageType_StellarManageDataOp: 220,
+      MessageType_StellarBumpSequenceOp: 221,
+      MessageType_StellarSignedTx: 230,
+    },
+  },
+};
+
+const fixtures = [
+  {
+    name: 'StellarPaymentOp',
+    in: {
+      source_account: 'meow'.repeat(100), // make message longer then 63 bytes
+      destination_account: 'wuff',
+      asset: {
+        type: 'NATIVE',
+        code: 'hello',
+        issuer: 'world',
+      },
+      amount: 10,
+    },
+  },
+];
+
+const parsedMessages = parseConfigure({
+  nested: { hw: { nested: { trezor: { nested: { messages: { nested: messages } } } } } },
+});
+
+describe('encoding json -> protobuf -> json', () => {
+  fixtures.forEach(f => {
+    describe(f.name, () => {
+      test('buildOne - receiveOne', () => {
+        // encoded message
+        const encodedMessage = buildOne(parsedMessages, f.name, f.in);
+        // then decode message and check, whether decoded message matches original json
+        const decodedMessage = receiveOne(parsedMessages, encodedMessage);
+        expect(decodedMessage.type).toEqual(f.name);
+        expect(decodedMessage.message).toEqual(f.in);
+      });
+
+      test('buildBuffers - receiveAndParse', () => {
+        const result = buildEncodeBuffers(parsedMessages, f.name, f.in);
+        result.forEach(r => {
+          expect(r.byteLength).toBeLessThanOrEqual(63);
+        });
+      });
+    });
+  });
+});

package/__tests__/decode-features.test.js

@@ -0,0 +1,72 @@
+const ProtoBuf = require('protobufjs/light');
+const ByteBuffer = require('bytebuffer');
+
+const { decode } = require('../src/serialization/protobuf/decode');
+const { decode: decodeProtocol } = require('../src/serialization/protocol/decode');
+
+// eslint-disable-next-line import/no-unresolved
+const messages = require('../messages.json');
+
+const fixtures = [
+  {
+    name: 'Features-error-battery_level',
+    encodeMessage:
+      '0011000000260a096f6e656b65792e736f1002180020002801900101aa010131b00101b80163c00163c020ff',
+    out: {
+      vendor: 'ukey.so',
+      major_version: 2,
+      minor_version: 0,
+      patch_version: 0,
+      bootloader_mode: true,
+      firmware_present: true,
+      capabilities: [],
+      model: '1',
+      fw_major: 1,
+      fw_minor: 99,
+      fw_patch: 99,
+      battery_level: 4,
+    },
+  },
+  {
+    name: 'Features-success',
+    encodeMessage:
+      '0011000000260a096f6e656b65792e736f1002180020002801900101aa010131b00102b80163c00163c02004',
+    out: {
+      vendor: 'ukey.so',
+      major_version: 2,
+      minor_version: 0,
+      patch_version: 0,
+      bootloader_mode: true,
+      firmware_present: true,
+      capabilities: [],
+      model: '1',
+      fw_major: 2,
+      fw_minor: 99,
+      fw_patch: 99,
+      battery_level: 4,
+    },
+  },
+];
+
+describe('Fix messages decode', () => {
+  const Messages = ProtoBuf.Root.fromJSON(messages);
+  const Message = Messages.lookup(`Features`);
+  fixtures.forEach(f => {
+    describe(f.name, () => {
+      test('decode', () => {
+        // deserialize
+        const encoded = ByteBuffer.fromHex(f.encodeMessage);
+        const { buffer } = decodeProtocol(encoded);
+        const decoded = decode(Message, buffer);
+
+        // filter null values
+        Object.keys(decoded).forEach(key => {
+          if (decoded[key] == null) {
+            delete decoded[key];
+          }
+        });
+        expect(decoded).toEqual(f.out);
+      });
+    });
+  });
+});

package/__tests__/encode-decode-basic.test.js

@@ -0,0 +1,272 @@
+const ProtoBuf = require('protobufjs/light');
+const { encode } = require('../src/serialization/protobuf/encode');
+const { decode } = require('../src/serialization/protobuf/decode');
+
+const messages = {
+  nested: {
+    messages: {
+      nested: {
+        String: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'string',
+              id: 1,
+            },
+          },
+        },
+        Uint32: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'uint32',
+              id: 2,
+            },
+          },
+        },
+        Uint64: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'uint64',
+              id: 3,
+            },
+          },
+        },
+        Bool: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'bool',
+              id: 4,
+            },
+          },
+        },
+        Sint32: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'sint32',
+              id: 5,
+            },
+          },
+        },
+        Sint64: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'sint64',
+              id: 6,
+            },
+          },
+        },
+        Bytes: {
+          fields: {
+            field: {
+              rule: 'required',
+              type: 'bytes',
+              id: 7,
+            },
+          },
+        },
+
+        //  complex and real life examples
+        ComplexFieldOfOptionals: {
+          fields: {
+            bool: {
+              rule: 'optional',
+              type: 'bool',
+              id: 8,
+            },
+            number: {
+              rule: 'optional',
+              type: 'uint32',
+              id: 9,
+            },
+          },
+        },
+
+        Repeated: {
+          fields: {
+            bool: {
+              rule: 'repeated',
+              type: 'bool',
+              id: 8,
+            },
+          },
+        },
+
+        Defaults: {
+          fields: {
+            string: {
+              type: 'string',
+              id: 8,
+              options: {
+                defaults: 'hello world',
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+const basicFixtures = [
+  {
+    name: 'String',
+    params: { field: 'foo' },
+    encoded: '0a03666f6f',
+  },
+  {
+    name: 'Uint32',
+    params: { field: 4294967295 },
+    encoded: '10ffffffff0f',
+  },
+  {
+    name: 'Uint64',
+    params: { field: 1844674407370955 },
+    encoded: '18cba19cd68bb7a303',
+  },
+  {
+    name: 'Uint64',
+    params: { field: '166054873161269248' }, // over Number.MAX_SAFE_INTEGER is sent as string
+    encoded: '1880808080f0c0fca602',
+  },
+  {
+    name: 'Sint64',
+    params: { field: '-166054873161269248' }, // over Number.MAX_SAFE_INTEGER is sent as string
+    encoded: '30ffffffffdf81f9cd04',
+  },
+  {
+    name: 'Bool',
+    params: { field: true },
+    encoded: '2001',
+  },
+  {
+    name: 'Bool',
+    params: { field: false },
+    encoded: '2000',
+  },
+  {
+    name: 'Sint32',
+    params: { field: -4294967 },
+    encoded: '28eda48c04',
+  },
+  {
+    name: 'Sint64',
+    params: { field: -1844674407370955 },
+    encoded: '3095c3b8ac97eec606',
+  },
+  {
+    name: 'Bytes',
+    params: {
+      field:
+        '851fc9542342321af63ecbba7d3ece545f2a42bad01ba32cff5535b18e54b6d3106e10b6a4525993d185a1443d9a125186960e028eabfdd8d76cf70a3a7e3100',
+    },
+    encoded:
+      '3a40851fc9542342321af63ecbba7d3ece545f2a42bad01ba32cff5535b18e54b6d3106e10b6a4525993d185a1443d9a125186960e028eabfdd8d76cf70a3a7e3100',
+  },
+];
+
+// note: difference in bool encoding. if type === bool && field = optional && not message of only one field, bool is encoded as ""
+const advancedFixtures = [
+  {
+    name: 'ComplexFieldOfOptionals',
+    in: { number: 1 },
+    encoded: '4801',
+    out: { bool: null, number: 1 },
+  },
+  {
+    name: 'Repeated',
+    in: { bool: [true, false, true, false] },
+    encoded: '420401000100',
+    out: { bool: [true, false, true, false] },
+  },
+  {
+    name: 'Defaults',
+    in: { string: '' },
+    encoded: '4200',
+    out: { string: '' },
+  },
+];
+
+describe('basic concepts', () => {
+  const Messages = ProtoBuf.Root.fromJSON(messages);
+
+  describe('primitives encode/decode', () => {
+    basicFixtures.forEach(f => {
+      describe(f.name, () => {
+        const Message = Messages.lookup(`messages.${f.name}`);
+
+        test(f.name, () => {
+          // serialize new way - this is to confirm new lib won't break old behavior
+          const encoded = encode(Message, f.params);
+          expect(encoded.toString('hex')).toEqual(f.encoded);
+
+          // deserialize new way - this is to confirm new lib won't break old behavior
+          const decoded = decode(Message, encoded);
+          expect(decoded).toEqual(f.params);
+        });
+      });
+    });
+  });
+
+  describe('advanced', () => {
+    advancedFixtures.forEach(f => {
+      describe(f.name, () => {
+        const Message = Messages.lookup(`messages.${f.name}`);
+
+        test(f.name, () => {
+          // serialize new way - this is to confirm new lib won't break old behavior
+          const encoded = encode(Message, f.in);
+
+          expect(encoded.toString('hex')).toEqual(f.encoded);
+
+          // deserialize new way - this is to confirm new lib won't break old behavior
+          const decoded = decode(Message, encoded);
+
+          expect(decoded).toEqual(f.out);
+        });
+      });
+    });
+
+    test('Different protobuf between receiving ends', () => {
+      const messages = {
+        nested: {
+          messages: {
+            nested: {
+              ButtonRequest: {
+                fields: {
+                  code: {
+                    type: 'string',
+                    id: 1,
+                  },
+                  pages: {
+                    type: 'uint32',
+                    id: 2,
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const SenderMessages = ProtoBuf.Root.fromJSON(messages);
+      const senderEncoded = encode(SenderMessages.lookup('messages.ButtonRequest'), {
+        type: 'foo',
+        pages: 123,
+      });
+
+      const receiverMessages = messages;
+      // now change field type from uint32 to string
+      receiverMessages.nested.messages.nested.ButtonRequest.fields.pages.type = 'string';
+      const ReceiverMessages = ProtoBuf.Root.fromJSON(receiverMessages);
+
+      expect(() => {
+        decode(ReceiverMessages.lookup('messages.ButtonRequest'), senderEncoded);
+      }).toThrow();
+    });
+  });
+});