Add did key spec 7 validators

.github/workflows/main.yml

@@ -24,7 +24,7 @@ jobs:
     timeout-minutes: 10
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x]
+        node-version: [16.x, 18.x]
     steps:
     - uses: actions/checkout@v2
     - name: Use Node.js ${{ matrix.node-version }}

CHANGELOG.md

@@ -1,5 +1,21 @@
 # did:key driver ChangeLog
 
+## 4.0.0 -
+
+### Added
+- **BREAKING**: Added validators for didDocument creation.
+- Added a `DidKeyDriver` options parameter to `didKeyDriver.{get, publicKeyToDidDoc, generate}`.
+- Added option `publicKeyFormat` to `DidKeyDriver` options.
+- Added option `enableEncryptionKeyDerivation` to `DidKeyDriver` options.
+- Added option `enableExperimentalPublicKeyTypes` to `DidKeyDriver` options.
+- Added option `defaultContext` to `DidKeyDriver` options.
+
+### Changed
+- **BREAKING**: `DidKeyDriver` now accepts a Map of `verificationMethods` in the constructor.
+
+### Removed
+- **BREAKING**: `DidKeyDriver` no longer takes a `verificationSuite` in the constructor.
+
 ## 3.0.0 - 2022-06-02
 
 ### Changed

README.md

@@ -184,9 +184,31 @@ To get a DID Document for an existing `did:key` DID:
 const did = 'did:key:z6MknCCLeeHBUaHu4aHSVLDCYQW9gjVJ7a63FpMvtuVMy53T';
 const didDocument = await didKeyDriver.get({did});
 ```
-
 (Results in the [example DID Doc](#example-did-document) above).
 
+### Options for `get`, `publicKeyToDidDoc`, and `generate`
+
+`get`, `publicKeyToDidDoc`, and `generate` both take an options object with the following options:
+
+```js
+const options = {
+  // default publicKeyFormat for the keys in the didDocument
+  publicKeyFormat: 'Ed25519VerificationKey2020',
+  // enableExperimentalPublicKeyTypes defaults to false. Setting it to true enables
+  // the use of key types that are not Multikey, JsonWebKey2020, or Ed25519VerificationKey2020.
+  enableExperimentalPublicKeyTypes: false,
+  // the context for the resulting did document
+  // the default is just the did context
+  defaultContext: [DID_CONTEXT_URL],
+  // if false no keyAgreementKey is included
+  // defaults to true
+  enableEncryptionKeyDerivation: true
+};
+
+const did = 'did:key:z6MknCCLeeHBUaHu4aHSVLDCYQW9gjVJ7a63FpMvtuVMy53T';
+const didDoc = await didKeyDriver.get({did, options});
+```
+
 #### Getting just the key object by key id
 
 You can also use a `.get()` to retrieve an individual key, if you know it's id
@@ -254,17 +276,17 @@ If you need DID Documents that are using the 2018/2019 crypto suites,
 you can customize the driver as follows.
 
 ```js
-import {
-  Ed25519VerificationKey2018
-} from '@digitalbazaar/ed25519-verification-key-2018';
 import * as didKey from '@digitalbazaar/did-method-key';
 
-const didKeyDriver2018 = didKey.driver({
- verificationSuite: Ed25519VerificationKey2018
-});
+const didKeyDriver = didKey.driver();
 
 const did = 'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH';
-await didKeyDriver2018.get({did});
+const options = {
+  publicKeyFormat: 'Ed25519VerificationKey2018',
+  // this defaults to false
+  enableExperimentalPublicKeyTypes: true
+};
+await didKeyDriver.get({did, options});
 // ->
 {
   '@context': [

lib/DidKeyDriver.js

@@ -1,64 +1,59 @@
 /*!
  * Copyright (c) 2021 Digital Bazaar, Inc. All rights reserved.
  */
-import {
-  Ed25519VerificationKey2020
-} from '@digitalbazaar/ed25519-verification-key-2020';
-import {
-  X25519KeyAgreementKey2020
-} from '@digitalbazaar/x25519-key-agreement-key-2020';
-import {
-  X25519KeyAgreementKey2019
-} from '@digitalbazaar/x25519-key-agreement-key-2019';
-
 import * as didIo from '@digitalbazaar/did-io';
-
+import {
+  parseDidKey,
+  validateDidDocument,
+  validateDidKey,
+  validatePublicKeyFormat
+} from './validators.js';
+import {DidResolverError} from '@digitalbazaar/did-io';
 const DID_CONTEXT_URL = 'https://www.w3.org/ns/did/v1';
-// For backwards compat only, not actually importing this suite
-const ED25519_KEY_2018_CONTEXT_URL =
-  'https://w3id.org/security/suites/ed25519-2018/v1';
-
-const contextsBySuite = new Map([
-  [Ed25519VerificationKey2020.suite, Ed25519VerificationKey2020.SUITE_CONTEXT],
-  ['Ed25519VerificationKey2018', ED25519_KEY_2018_CONTEXT_URL],
-  [X25519KeyAgreementKey2020.suite, X25519KeyAgreementKey2020.SUITE_CONTEXT],
-  [X25519KeyAgreementKey2019.suite, X25519KeyAgreementKey2019.SUITE_CONTEXT]
-]);
+import {
+  contextsBySuite,
+  getEncryptionMethod,
+  methodsByKeyFormat
+} from './verificationMethods.js';
 
 export class DidKeyDriver {
   /**
-   * @param {object} options - Options hashmap.
-   * @param {object} [options.verificationSuite=Ed25519VerificationKey2020] -
-   *   Key suite for the signature verification key suite to use.
+   * @param {object} options - Options to use.
+   * @param {Map<string, object>} [options.verificationMethods] -
+   *   A map of verification methods with the key as the publicKeyFormat.
    */
-  constructor({verificationSuite = Ed25519VerificationKey2020} = {}) {
+  constructor({
+    verificationMethods = methodsByKeyFormat,
+  } = {}) {
     // used by did-io to register drivers
     this.method = 'key';
-    this.verificationSuite = verificationSuite;
+    this.verificationMethods = verificationMethods;
   }
 
   /**
    * Generates a new `did:key` method DID Document (optionally, from a
    * deterministic seed value).
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @param {Uint8Array} [options.seed] - A 32-byte array seed for a
    *   deterministic key.
+   * @param {object} [options.options] - DID Document creation options.
    *
    * @returns {Promise<{didDocument: object, keyPairs: Map,
    *   methodFor: Function}>} Resolves with the generated DID Document, along
    *   with the corresponding key pairs used to generate it (for storage in a
    *   KMS).
    */
-  async generate({seed} = {}) {
+  async generate({seed, options = {}} = {}) {
     // Public/private key pair of the main did:key signing/verification key
-    const verificationKeyPair = await this.verificationSuite.generate({seed});
-
+    const verificationKeyPair = await this._getVerificationMethod(options).
+      generate({seed});
     // keyPairs is a map of keyId to key pair instance, that includes
     // the verificationKeyPair above, but also the keyAgreementKey pair that
     // is derived from the verification key pair.
     const {didDocument, keyPairs} = await this._keyPairToDidDocument({
-      keyPair: verificationKeyPair
+      keyPair: verificationKeyPair,
+      options
     });
 
     // Convenience function that returns the public/private key pair instance
@@ -86,7 +81,7 @@ export class DidKeyDriver {
    * const authPublicKey = await cryptoLd.from(authKeyData);
    * const {verify} = authPublicKey.verifier();
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @param {object} options.didDocument - DID Document (retrieved via a
    *   `.get()` or from some other source).
    * @param {string} options.purpose - Verification method purpose, such as
@@ -119,27 +114,29 @@ export class DidKeyDriver {
    * await resolver.get({did}); // -> did document
    * await resolver.get({url: keyId}); // -> public key node
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @param {string} [options.did] - DID URL or a key id (either an ed25519 key
    *   or an x25519 key-agreement key id).
    * @param {string} [options.url] - Alias for the `did` url param, supported
    *   for better readability of invoking code.
+   * @param {object} [options.options] - Options for didDocument creation.
    *
    * @returns {Promise<object>} Resolves to a DID Document or a
    *   public key node with context.
    */
-  async get({did, url} = {}) {
+  async get({did, url, options} = {}) {
     did = did || url;
     if(!did) {
       throw new TypeError('"did" must be a string.');
     }
+    validateDidKey({did});
 
     const [didAuthority, keyIdFragment] = did.split('#');
+    const {multibase: fingerprint} = parseDidKey({did: didAuthority});
+    const keyPair = this._getVerificationMethod(options).
+      fromFingerprint({fingerprint});
 
-    const fingerprint = didAuthority.substr('did:key:'.length);
-    const keyPair = this.verificationSuite.fromFingerprint({fingerprint});
-
-    const {didDocument} = await this._keyPairToDidDocument({keyPair});
+    const {didDocument} = await this._keyPairToDidDocument({keyPair, options});
 
     if(keyIdFragment) {
       // resolve an individual key
@@ -155,67 +152,55 @@ export class DidKeyDriver {
    * Note that unlike `generate()`, a `keyPairs` map is not returned. Use
    * `publicMethodFor()` to fetch keys for particular proof purposes.
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @typedef LDKeyPair
    * @param {LDKeyPair|object} options.publicKeyDescription - Public key object
    *   used to generate the DID document (either an LDKeyPair instance
    *   containing public key material, or a "key description" plain object
    *   (such as that generated from a KMS)).
+   * @param {object} [options.options] - Options for didDocument creation.
    *
    * @returns {Promise<object>} Resolves with the generated DID Document.
    */
-  async publicKeyToDidDoc({publicKeyDescription} = {}) {
+  async publicKeyToDidDoc({publicKeyDescription, options} = {}) {
     const {didDocument} = await this._keyPairToDidDocument({
-      keyPair: publicKeyDescription
+      keyPair: publicKeyDescription,
+      options
     });
     return {didDocument};
   }
 
   /**
    * Converts an Ed25519KeyPair object to a `did:key` method DID Document.
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @param {LDKeyPair|object} options.keyPair - Key used to generate the DID
    *   document (either an LDKeyPair instance containing public key material,
    *   or a "key description" plain object (such as that generated from a KMS)).
+   * @param {object} [options.options = {}] - Options for didDocument creation.
    *
    * @returns {Promise<{didDocument: object, keyPairs: Map}>}
    *   Resolves with the generated DID Document, along with the corresponding
    *   key pairs used to generate it (for storage in a KMS).
    */
-  async _keyPairToDidDocument({keyPair} = {}) {
-    const verificationKeyPair = await this.verificationSuite.from({...keyPair});
+  async _keyPairToDidDocument({keyPair, options = {}} = {}) {
+    const {
+      publicKeyFormat = 'Ed25519VerificationKey2020',
+      enableExperimentalPublicKeyTypes = false,
+      defaultContext = [DID_CONTEXT_URL],
+      enableEncryptionKeyDerivation = true
+    } = options;
+    const verificationKeyPair = await this._getVerificationMethod(
+      {publicKeyFormat}).from({...keyPair});
     const did = `did:key:${verificationKeyPair.fingerprint()}`;
     verificationKeyPair.controller = did;
 
-    const contexts = [DID_CONTEXT_URL];
-
-    // The KAK pair will use the source key's controller, but will generate
-    // its own .id
-    let keyAgreementKeyPair;
-    if(verificationKeyPair.type === 'Ed25519VerificationKey2020') {
-      keyAgreementKeyPair = X25519KeyAgreementKey2020
-        .fromEd25519VerificationKey2020({keyPair: verificationKeyPair});
-      contexts.push(Ed25519VerificationKey2020.SUITE_CONTEXT,
-        X25519KeyAgreementKey2020.SUITE_CONTEXT);
-    } else if(verificationKeyPair.type === 'Ed25519VerificationKey2018') {
-      keyAgreementKeyPair = X25519KeyAgreementKey2019
-        .fromEd25519VerificationKey2018({keyPair: verificationKeyPair});
-      contexts.push(ED25519_KEY_2018_CONTEXT_URL,
-        X25519KeyAgreementKey2019.SUITE_CONTEXT);
-    } else {
-      throw new Error(
-        'Cannot derive key agreement key from verification key type "' +
-          verificationKeyPair.type + '".'
-      );
-    }
-
+    const contexts = [...defaultContext];
     // Now set the source key's id
     verificationKeyPair.id = `${did}#${verificationKeyPair.fingerprint()}`;
 
     // get the public components of each keypair
     const publicEdKey = verificationKeyPair.export({publicKey: true});
-    const publicDhKey = keyAgreementKeyPair.export({publicKey: true});
 
     // Compose the DID Document
     const didDocument = {
@@ -227,22 +212,54 @@ export class DidKeyDriver {
       authentication: [publicEdKey.id],
       assertionMethod: [publicEdKey.id],
       capabilityDelegation: [publicEdKey.id],
-      capabilityInvocation: [publicEdKey.id],
-      keyAgreement: [publicDhKey]
+      capabilityInvocation: [publicEdKey.id]
     };
-
     // create the key pairs map
     const keyPairs = new Map();
     keyPairs.set(verificationKeyPair.id, verificationKeyPair);
-    keyPairs.set(keyAgreementKeyPair.id, keyAgreementKeyPair);
+
+    // don't include an encryption verification method unless the option is true
+    if(enableEncryptionKeyDerivation) {
+      // The KAK pair will use the source key's controller, but will generate
+      // its own .id
+      const keyAgreementKeyPair = getEncryptionMethod({
+        verificationKeyPair,
+        contexts
+      });
+      keyPairs.set(keyAgreementKeyPair.id, keyAgreementKeyPair);
+      const publicDhKey = keyAgreementKeyPair.export({publicKey: true});
+      didDocument.keyAgreement = [publicDhKey];
+    }
+    validateDidDocument({
+      didDocument,
+      didOptions: {
+        enableExperimentalPublicKeyTypes,
+        enableEncryptionKeyDerivation
+      }
+    });
 
     return {didDocument, keyPairs};
   }
-
+  _getVerificationMethod({
+    publicKeyFormat = 'Ed25519VerificationKey2020'
+  } = {}) {
+    // ensure public key format is a format we have an implementation of
+    validatePublicKeyFormat({publicKeyFormat});
+    const verificationMethod = this.verificationMethods.get(publicKeyFormat);
+    // if there is no verificationMethod then the method is not supported by
+    // the `did:key` spec
+    if(!verificationMethod) {
+      throw new DidResolverError({
+        message: `Unsupported public key type ${publicKeyFormat}`,
+        code: 'unsupportedPublicKeyType'
+      });
+    }
+    return verificationMethod;
+  }
   /**
    * Computes and returns the id of a given key pair. Used by `did-io` drivers.
    *
-   * @param {object} options - Options hashmap.
+   * @param {object} options - Options object.
    * @param {LDKeyPair} options.keyPair - The key pair used when computing the
    *   identifier.
    *
@@ -256,7 +273,7 @@ export class DidKeyDriver {
 /**
  * Returns the public key object for a given key id fragment.
  *
- * @param {object} options - Options hashmap.
+ * @param {object} options - Options object.
  * @param {object} options.didDocument - The DID Document to use when generating
  *   the id.
  * @param {string} options.keyIdFragment - The key identifier fragment.

lib/index.js

@@ -7,14 +7,14 @@ import {DidKeyDriver} from './DidKeyDriver.js';
 /**
  * Helper method to match the `.driver()` API of other `did-io` plugins.
  *
- * @param {object} options - Options hashmap.
- * @param {object} [options.verificationSuite=Ed25519VerificationKey2020] -
- *   Key suite for the signature verification key suite to use.
+ * @param {object} options - Options object.
+ * @param {Map<string, object>} [options.verificationMethods] -
+ *   A map of verification methods with the key as the publicKeyFormat.
  *
  * @returns {DidKeyDriver} Returns an instance of a did:key resolver driver.
  */
-function driver({verificationSuite} = {}) {
-  return new DidKeyDriver({verificationSuite});
+function driver({verificationMethods} = {}) {
+  return new DidKeyDriver({verificationMethods});
 }
 
 export {driver, DidKeyDriver};