Refactor @web5/dids to support first class Key Management

packages/agent/.c8rc.json

@@ -5,12 +5,12 @@
     ".js"
   ],
   "include": [
-    "tests/compiled/src/**"
+    "tests/compiled/**/src/**"
   ],
   "exclude": [
-    "tests/compiled/src/index.js",
-    "tests/compiled/src/types.js",
-    "tests/compiled/src/types/**"
+    "tests/compiled/**/src/index.js",
+    "tests/compiled/**/src/types.js",
+    "tests/compiled/**/src/types/**"
   ],
   "reporter": [
     "cobertura",

packages/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web5/agent",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -69,7 +69,7 @@
   },
   "dependencies": {
     "@tbd54566975/dwn-sdk-js": "0.2.10",
-    "@web5/common": "0.2.2",
+    "@web5/common": "0.2.3",
     "@web5/crypto": "0.2.2",
     "@web5/dids": "0.2.4",
     "level": "8.0.0",
@@ -81,6 +81,7 @@
     "@playwright/test": "1.40.1",
     "@types/chai": "4.3.6",
     "@types/chai-as-promised": "7.1.5",
+    "@types/dns-packet": "5.6.4",
     "@types/eslint": "8.44.2",
     "@types/mocha": "10.0.1",
     "@types/readable-stream": "4.0.6",
@@ -89,7 +90,7 @@
     "@typescript-eslint/parser": "6.4.0",
     "@web/test-runner": "0.18.0",
     "@web/test-runner-playwright": "0.11.0",
-    "c8": "8.0.1",
+    "c8": "9.0.0",
     "chai": "4.3.10",
     "chai-as-promised": "7.1.1",
     "esbuild": "0.19.8",

packages/api/.c8rc.json

@@ -5,12 +5,12 @@
     ".js"
   ],
   "include": [
-    "tests/compiled/src/**"
+    "tests/compiled/**/src/**"
   ],
   "exclude": [
-    "tests/compiled/src/index.js",
-    "tests/compiled/src/types.js",
-    "tests/compiled/src/types/**"
+    "tests/compiled/**/src/index.js",
+    "tests/compiled/**/src/types.js",
+    "tests/compiled/**/src/types/**"
   ],
   "reporter": [
     "cobertura",

packages/api/package.json

@@ -77,11 +77,11 @@
   },
   "dependencies": {
     "@tbd54566975/dwn-sdk-js": "0.2.10",
-    "@web5/agent": "0.2.5",
-    "@web5/common": "0.2.2",
+    "@web5/agent": "0.2.6",
+    "@web5/common": "0.2.3",
     "@web5/crypto": "0.2.2",
     "@web5/dids": "0.2.4",
-    "@web5/user-agent": "0.2.5",
+    "@web5/user-agent": "0.2.6",
     "level": "8.0.0",
     "ms": "2.1.3",
     "readable-stream": "4.4.2",
@@ -100,7 +100,7 @@
     "@typescript-eslint/parser": "6.4.0",
     "@web/test-runner": "0.18.0",
     "@web/test-runner-playwright": "0.11.0",
-    "c8": "8.0.1",
+    "c8": "9.0.0",
     "chai": "4.3.10",
     "chai-as-promised": "7.1.1",
     "esbuild": "0.19.8",
@@ -112,7 +112,7 @@
     "playwright": "1.40.1",
     "rimraf": "4.4.0",
     "sinon": "16.1.3",
-    "source-map-loader": "4.0.1",
+    "source-map-loader": "4.0.2",
     "typescript": "5.1.6"
   }
 }

packages/common/.c8rc.json

@@ -5,12 +5,12 @@
     ".js"
   ],
   "include": [
-    "tests/compiled/src/**"
+    "tests/compiled/**/src/**"
   ],
   "exclude": [
-    "tests/compiled/src/index.js",
-    "tests/compiled/src/types.js",
-    "tests/compiled/src/types/**"
+    "tests/compiled/**/src/index.js",
+    "tests/compiled/**/src/types.js",
+    "tests/compiled/**/src/types/**"
   ],
   "reporter": [
     "cobertura",

packages/common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web5/common",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -83,7 +83,7 @@
     "@typescript-eslint/parser": "6.4.0",
     "@web/test-runner": "0.18.0",
     "@web/test-runner-playwright": "0.11.0",
-    "c8": "8.0.1",
+    "c8": "9.0.0",
     "chai": "4.3.10",
     "chai-as-promised": "7.1.1",
     "esbuild": "0.19.8",

packages/common/src/convert.ts

@@ -1,5 +1,6 @@
 import type { Multibase } from 'multiformats';
 
+import { base32z } from 'multiformats/bases/base32';
 import { base58btc } from 'multiformats/bases/base58';
 import { base64url } from 'multiformats/bases/base64';
 
@@ -28,6 +29,10 @@ export class Convert {
     return new Convert(data, 'AsyncIterable');
   }
 
+  static base32Z(data: string): Convert {
+    return new Convert(data, 'Base32Z');
+  }
+
   static base58Btc(data: string): Convert {
     return new Convert(data, 'Base58Btc');
   }
@@ -131,6 +136,18 @@ export class Convert {
     }
   }
 
+  toBase32Z(): string {
+    switch (this.format) {
+
+      case 'Uint8Array': {
+        return base32z.baseEncode(this.data);
+      }
+
+      default:
+        throw new TypeError(`Conversion from ${this.format} to Base64Z is not supported.`);
+    }
+  }
+
   toBase58Btc(): string {
     switch (this.format) {
 
@@ -357,6 +374,10 @@ export class Convert {
         return new Uint8Array(this.data);
       }
 
+      case 'Base32Z': {
+        return base32z.baseDecode(this.data);
+      }
+
       case 'Base58Btc': {
         return base58btc.baseDecode(this.data);
       }

packages/common/src/type-utils.ts

@@ -1,3 +1,67 @@
+/**
+ * Represents an array of a fixed length, preventing modifications to its size.
+ *
+ * The `FixedLengthArray` utility type transforms a standard array into a variant where
+ * methods that could alter the length are omitted. It leverages TypeScript's advanced types,
+ * such as conditional types and mapped types, to ensure that the array cannot be resized
+ * through methods like `push`, `pop`, `splice`, `shift`, and `unshift`. The utility type
+ * maintains all other characteristics of a standard array, including indexing, iteration,
+ * and type checking for its elements.
+ *
+ * Note: The type does not prevent direct assignment to indices, even if it would exceed
+ * the original length. However, such actions would lead to TypeScript type errors.
+ *
+ * @example
+ * ```ts
+ * // Declare a variable with a type of fixed-length array of three strings.
+ * let myFixedLengthArray: FixedLengthArray< [string, string, string]>;
+ *
+ * // Array declaration tests
+ * myFixedLengthArray = [ 'a', 'b', 'c' ];  // OK
+ * myFixedLengthArray = [ 'a', 'b', 123 ];  // TYPE ERROR
+ * myFixedLengthArray = [ 'a' ];            // LENGTH ERROR
+ * myFixedLengthArray = [ 'a', 'b' ];       // LENGTH ERROR
+ *
+ * // Index assignment tests
+ * myFixedLengthArray[1] = 'foo';           // OK
+ * myFixedLengthArray[1000] = 'foo';        // INVALID INDEX ERROR
+ *
+ * // Methods that mutate array length
+ * myFixedLengthArray.push('foo');          // MISSING METHOD ERROR
+ * myFixedLengthArray.pop();                // MISSING METHOD ERROR
+ *
+ * // Direct length manipulation
+ * myFixedLengthArray.length = 123;         // READ-ONLY ERROR
+ *
+ * // Destructuring
+ * let [ a ] = myFixedLengthArray;          // OK
+ * let [ a, b ] = myFixedLengthArray;       // OK
+ * let [ a, b, c ] = myFixedLengthArray;    // OK
+ * let [ a, b, c, d ] = myFixedLengthArray; // INVALID INDEX ERROR
+ * ```
+ *
+ * @template T extends any[] - The array type to be transformed.
+ */
+export type FixedLengthArray<T extends any[]> =
+  Pick<T, Exclude<keyof T, ArrayLengthMutationKeys>>
+  & {
+    /**
+     * Custom iterator for the `FixedLengthArray` type.
+     *
+     * This iterator allows the `FixedLengthArray` to be used in standard iteration
+     * contexts, such as `for...of` loops and spread syntax. It ensures that even though
+     * the array is of a fixed length with disabled mutation methods, it still retains
+     * iterable behavior similar to a regular array.
+     *
+     * @returns An IterableIterator for the array items.
+     */
+    [Symbol.iterator]: () => IterableIterator<ArrayItems<T>>
+  };
+
+/** Helper types for {@link FixedLengthArray} */
+type ArrayLengthMutationKeys = 'splice' | 'push' | 'pop' | 'shift' | 'unshift' | number;
+type ArrayItems<T extends Array<any>> = T extends Array<infer TItems> ? TItems : never;
+
 /**
  * isArrayBufferSlice
  *
@@ -72,6 +136,34 @@ export function isDefined<T>(arg: T): arg is Exclude<T, null | undefined> {
   return arg !== null && typeof arg !== 'undefined';
 }
 
+/**
+ * Utility type that transforms a type `T` to have only certain keys `K` as required, while the
+ * rest remain optional, except for keys specified in `O`, which are omitted entirely.
+ *
+ * This type is useful when you need a variation of a type where only specific properties are
+ * required, and others are either optional or not included at all. It allows for more flexible type
+ * definitions based on existing types without the need to redefine them.
+ *
+ * @template T - The original type to be transformed.
+ * @template K - The keys of `T` that should be required.
+ * @template O - The keys of `T` that should be omitted from the resulting type (optional).
+ *
+ * @example
+ * ```ts
+ * // Given an interface
+ * interface Example {
+ *   requiredProp: string;
+ *   optionalProp?: number;
+ *   anotherOptionalProp?: boolean;
+ * }
+ *
+ * // Making 'optionalProp' required and omitting 'anotherOptionalProp'
+ * type ModifiedExample = RequireOnly<Example, 'optionalProp', 'anotherOptionalProp'>;
+ * // Result: { requiredProp?: string; optionalProp: number; }
+ * ```
+ */
+export type RequireOnly<T, K extends keyof T, O extends keyof T = never> = Required<Pick<T, K>> & Omit<Partial<T>, O>;
+
 /**
  * universalTypeOf
  *
@@ -114,4 +206,27 @@ export function universalTypeOf(value: unknown) {
   const [_, type] = match as RegExpMatchArray;
 
   return type;
-}
+}
+
+/**
+ * Utility type to extract the type resolved by a Promise.
+ *
+ * This type unwraps the type `T` from `Promise<T>` if `T` is a Promise, otherwise returns `T` as
+ * is. It's useful in situations where you need to handle the type returned by a promise-based
+ * function in a synchronous context, such as defining types for test vectors or handling return
+ * types in non-async code blocks.
+ *
+ * @template T - The type to unwrap from the Promise.
+ *
+ * @example
+ * ```ts
+ * // For a Promise type, it extracts the resolved type.
+ * type AsyncNumber = Promise<number>;
+ * type UnwrappedNumber = UnwrapPromise<AsyncNumber>; // number
+ *
+ * // For a non-Promise type, it returns the type as is.
+ * type StringValue = string;
+ * type UnwrappedString = UnwrapPromise<StringValue>; // string
+ * ```
+ */
+export type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

packages/common/src/types.ts

@@ -40,9 +40,4 @@ export interface KeyValueStore<K, V> {
    * @returns A promise that resolves when the value has been set.
    */
   set(key: K, value: V): Promise<void>;
-}
-
-/**
- * Represents an object type where a subset of keys are required and everything else is optional.
- */
-export type RequireOnly<T, K extends keyof T, O extends keyof T = never> = Required<Pick<T, K>> & Omit<Partial<T>, O>;
+}

packages/common/tests/convert.spec.ts

@@ -236,6 +236,23 @@ describe('Convert', () =>{
     });
   });
 
+  describe('from: Base64Z', () => {
+    it('to: Uint8Array', () => {
+      // Test Vector 1.
+      let input = '5umembtazeybqcd7grysfp711g1z56wzo8irzhae494hh58zguhy';
+      let output = new Uint8Array([
+        220, 214, 133, 134,  56, 186,   0,  23,
+        48,  125,  49,   1,  98, 183, 178, 145,
+        165, 125, 250, 151, 129, 234,  75, 243,
+        8,   215, 245, 206, 108, 247,  52, 248
+      ]);
+
+      let result = Convert.base32Z(input).toUint8Array();
+
+      expect(result).to.deep.equal(output);
+    });
+  });
+
   describe('from: BufferSource', () => {
     it('to: ArrayBuffer', () => {
       // Test Vector 1 - BufferSource is Uint8Array.
@@ -500,6 +517,21 @@ describe('Convert', () =>{
       expect(result).to.deep.equal(output);
     });
 
+    it('to: Base32Z', () => {
+      // Test Vector 1.
+      let input = new Uint8Array([
+        220, 214, 133, 134,  56, 186,   0,  23,
+        48,  125,  49,   1,  98, 183, 178, 145,
+        165, 125, 250, 151, 129, 234,  75, 243,
+        8,   215, 245, 206, 108, 247,  52, 248
+      ]);
+      let output = '5umembtazeybqcd7grysfp711g1z56wzo8irzhae494hh58zguhy';
+
+      let result = Convert.uint8Array(input).toBase32Z();
+
+      expect(result).to.deep.equal(output);
+    });
+
     it('to: Base58Btc', () => {
       // Test Vector 1.
       let input = new Uint8Array([51, 52, 53]);
@@ -567,6 +599,10 @@ describe('Convert', () =>{
       }
     });
 
+    it('toBase32Z() throw an error', () => {
+      expect(() => unsupported.toBase32Z()).to.throw(TypeError, 'not supported');
+    });
+
     it('toBase58Btc() throw an error', () => {
       expect(() => unsupported.toBase58Btc()).to.throw(TypeError, 'not supported');
     });