bnid - npm Package Compare versions

Comparing version 2.0.0 to 2.1.0

CHANGELOG.md

 # bnid ChangeLog
 
+## 2.1.0 - 2021-11-18
+
+### Added
+- Add `generateSecretKeySeed()` and `decodeSecretKeySeed()`.
+- Add `multihash` boolean parameter to IdEncoder and IdDecoder. A
+  multihash-encoded identifier will use the `identity` multicodec tag (`0x00`).
+  Using multihash has the advantage of including the size of the identifier
+  which can then be verified to have not changed when decoding.
+- Add `expectedSize` optional parameter to IdDecoder for multihash-encoded ID
+  bytes. (default: 32).
+
 ## 2.0.0 - 2020-05-22
@@ -4,0 +15,0 @@

main.js

@@ -14,2 +14,5 @@ /*!
 
+// multihash identity function code
+const MULTIHASH_IDENTITY_FUNCTION_CODE = 0x00;
+
 function _calcOptionsBitLength({
@@ -157,2 +160,3 @@ defaultLength,
    * @param {boolean} [options.multibase=true] - Use multibase encoding.
+   * @param {boolean} [options.multihash=false] - Use multihash encoding.
    *
@@ -165,3 +169,4 @@ * @returns {IdEncoder} - New IdEncoder.
     fixedBitLength,
-    multibase = true
+    multibase = true,
+    multihash = false,
   } = {}) {
@@ -196,2 +201,3 @@ switch(encoding) {
     this.multibase = multibase;
+    this.multihash = multihash;
   }
@@ -207,2 +213,19 @@
   encode(bytes) {
+    if(this.multihash) {
+      const byteSize = bytes.length;
+
+      if(byteSize > 127) {
+        throw new RangeError('Identifier size too large.');
+      }
+      // <varint hash fn code> <varint digest size in bytes> <hash fn output>
+      //  <identity function>             <byte size>                <raw bytes>
+      const multihash = new Uint8Array(2 + byteSize);
+      // <varint hash fn code>: identity function
+      multihash.set([MULTIHASH_IDENTITY_FUNCTION_CODE]);
+      // <varint digest size in bytes>
+      multihash.set([byteSize], 1);
+      // <hash fn output>: identifier bytes
+      multihash.set(bytes, 2);
+      bytes = multihash;
+    }
     const encoded = this.encoder({bytes, idEncoder: this});
@@ -231,3 +254,7 @@ if(this.multibase) {
    *   detect the id format.
-   *
+   * @param {boolean} [options.multihash=false] - Use multihash encoding to
+   *   detect the id format.
+   * @param {number} [options.expectedSize=32] - Optional expected identifier
+   *   size in bytes (only for multihash encoding). Use `0` to disable size
+   *   check.
    * @returns {IdDecoder} - New IdDecoder.
@@ -238,3 +265,5 @@ */
     fixedBitLength,
-    multibase = true
+    multibase = true,
+    multihash = false,
+    expectedSize = 32
   } = {}) {
@@ -244,2 +273,4 @@ this.encoding = encoding;
     this.multibase = multibase;
+    this.multihash = multihash;
+    this.expectedSize = expectedSize;
   }
@@ -305,2 +336,29 @@
     }
+    if(this.multihash) {
+      // <varint hash fn code>: identity function
+      const [hashFnCode] = decoded;
+
+      if(hashFnCode !== MULTIHASH_IDENTITY_FUNCTION_CODE) {
+        throw new Error('Invalid multihash function code.');
+      }
+      // <varint digest size in bytes>
+      const digestSize = decoded[1];
+
+      if(digestSize > 127) {
+        throw new RangeError('Decoded identifier size too large.');
+      }
+
+      const bytes = decoded.subarray(2);
+
+      if(bytes.byteLength !== digestSize) {
+        throw new RangeError('Unexpected identifier size.');
+      }
+      if(this.expectedSize && bytes.byteLength !== this.expectedSize) {
+        throw new RangeError(
+          `Invalid decoded identifier size. Identifier must be ` +
+            `"${this.expectedSize}" bytes.`);
+      }
+
+      decoded = bytes;
+    }
     return decoded;
@@ -399,1 +457,57 @@ }
 }
+
+/**
+ * Generates a secret key seed encoded as a string that can be stored and later
+ * used to generate a key pair. The public key from the key pair can be used as
+ * an identifier. The key seed (both raw and encoded form) MUST be kept secret.
+ *
+ * @param {object} [options] - The options to use.
+ * @param {string} [options.encoding='base58'] - Encoding format.
+ * @param {number} [options.bitLength=32 * 8] - Number of bits to generate.
+ * @param {boolean} [options.multibase=true] - Use multibase encoding.
+ * @param {boolean} [options.multihash=true] - Use multihash encoding.
+
+ * @returns {string} - Secret key seed encoded as a string.
+ */
+export async function generateSecretKeySeed({
+  bitLength = 32 * 8,
+  encoding = 'base58',
+  multibase = true,
+  multihash = true
+} = {}) {
+  // reuse `generateId` for convenience, but a key seed is *SECRET* and
+  // not an identifier itself, rather it is used to generate an identifier via
+  // a public key
+  // Note: Setting fixedLength to false even though that's the (current)
+  // default as not using a fixed length of false for a seed is a security
+  // problem
+  return generateId(
+    {bitLength, encoding, fixedLength: false, multibase, multihash});
+}
+
+/**
+ * Decodes an encoded secret key seed into an array of secret key seed bytes.
+ * The key seed bytes MUST be kept secret.
+ *
+ * @param {object} options - The options to use.
+ * @param {boolean} [options.multibase=true] - Use multibase encoding to detect
+ *   the id format.
+ * @param {boolean} [options.multihash=true] - Use multihash encoding to detect
+ *   the id format.
+ * @param {number} [options.expectedSize] - Optional expected identifier size
+ *   in bytes (only for multihash encoding). Use `0` to disable size check.
+ * @param {string} options.secretKeySeed - The secret key seed to be decoded.
+ *
+ * @returns {Uint8Array} - An array of secret key seed bytes (default size:
+ *   32 bytes).
+ */
+export function decodeSecretKeySeed({
+  multibase = true,
+  multihash = true,
+  expectedSize = 32,
+  secretKeySeed,
+}) {
+  // reuse `decodeId` for convenience, but key seed bytes are *SECRET* and
+  // are NOT identifiers, they are used to generate identifiers from public keys
+  return decodeId({multihash, multibase, expectedSize, id: secretKeySeed});
+}

package.json

 {
   "name": "bnid",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Base-N Id Generator",
@@ -17,3 +17,3 @@ "license": "BSD-3-Clause",
   "bugs": {
-    "url": "https://github.com/digitalbazaar/edv-client/issues"
+    "url": "https://github.com/digitalbazaar/bnid/issues"
   },
@@ -20,0 +20,0 @@ "keywords": [

README.md

@@ -180,2 +180,3 @@ # JavaScript Base-N Id Generator _(bnid)_
 - `multibase`: `true` to use multibase encoding. (default: `true`)
+- `multihash`: `true` to use multihash encoding. (default: `false`)
 
@@ -188,3 +189,4 @@ #### `encode(bytes)`
 
-An `IdEncoder` encodes an array of id bytes into a specific encoding.
+An `IdDecoder` decodes a specific encoding into an array of bytes representing
+an ID.
 
@@ -199,3 +201,6 @@ #### `constuctor(options)`
 - `multibase`: `true` to use multibase encoding to detect id format. (default:
-  `false`)
+  `true`)
+- `multihash`: `true` to use multihash encoding. (default: `false`)
+- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to
+  disable size check. (default: 32)
 
@@ -224,2 +229,49 @@ #### `decode(id)`
 
+### `generateSecretKeySeed(options)`
+
+`generateSecretKeySeed()` and `decodeSecretKeySeed()` methods are for creating
+and decoding secret key pair seeds which can be used to generate public key
+based identifiers.
+
+`generateSecretKeySeed()` generates a secret key seed encoded as a string that
+can be stored and later used to generate a key pair. The public key from
+the key pair can be used as an identifier. The encoded key seed MUST be kept
+secret.
+
+```js
+import {generateSecretKeySeed} from 'bnid';
+const secretKeySeed = await generateSecretKeySeed();
+// Example secretKeySeed: z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD
+```
+Options:
+- `encoding`: Encoding. (default: `base58`)
+- `bitLength`: Number of id bits. (default: 32 * 8)
+- `multibase`: Account for multibase encoding. (default: true)
+- `multihash`: Account for multihash encoding. (default: true)
+
+### `decodeSecretKeySeed(options)`
+
+Decodes an encoded secret key seed into an array of secret key seed bytes
+(default size: 32 bytes). Both the encoded key seed and the decoded bytes MUST
+be kept secret.
+
+```js
+import {decodeSecretKeySeed} from 'bnid';
+const secretKeySeed = 'z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD';
+decoded = decodeSecretKeySeed({secretKeySeed});
+// Example decoded:
+// Uint8Array(32) [
+//    80, 174,  15, 131, 124,  59,   9,  51,
+//   145, 129,  92, 157, 157, 172, 161,  79,
+//    74,  61, 152, 152,  48, 151,  20,  89,
+//   225, 169,  71,  34,  49,  61,  21, 215
+// ]
+```
+Options:
+- `secretKeySeed`: The secret key seed to be decoded.
+- `multibase`: Account for multibase encoding. (default: true)
+- `multihash`: Account for multihash encoding. (default: true)
+- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to
+  disable size check. (default: 32)
+
 ## CLI
@@ -226,0 +278,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

30996

increased by28.48%

Lines of code

516

increased by25.24%

Number of lines in readme file

341

increased by17.99%

No dependency changes