@interop/did-web-resolver 0.2.0 → 2.0.0

package/src/DidWebResolver.js

@@ -1,17 +1,17 @@
-'use strict'
-
-// import axios from 'axios' // todo: consider 'apisauce' instead
-import { DidDocument } from 'did-io'
-import { URL } from 'whatwg-url'
+import { httpClient } from '@digitalbazaar/http-client'
+import * as didIo from '@digitalbazaar/did-io'
+import ed25519Context from 'ed25519-signature-2020-context'
+import x25519Context from 'x25519-key-agreement-2020-context'
 import didContext from 'did-context'
-const DID_CONTEXT_URL = didContext.constants.DID_CONTEXT_URL
+
+const { VERIFICATION_RELATIONSHIPS } = didIo
 
 const DEFAULT_KEY_MAP = {
-  capabilityInvocation: 'Ed25519VerificationKey2018',
-  authentication: 'Ed25519VerificationKey2018',
-  assertionMethod: 'Ed25519VerificationKey2018',
-  capabilityDelegation: 'Ed25519VerificationKey2018'
-  // keyAgreement: 'X25519KeyAgreementKey2019'  // <- not yet supported
+  capabilityInvocation: 'Ed25519VerificationKey2020',
+  authentication: 'Ed25519VerificationKey2020',
+  assertionMethod: 'Ed25519VerificationKey2020',
+  capabilityDelegation: 'Ed25519VerificationKey2020',
+  keyAgreement: 'X25519KeyAgreementKey2020'
 }
 
 export function didFromUrl ({ url } = {}) {
@@ -47,59 +47,256 @@ export function urlFromDid ({ did } = {}) {
     throw new TypeError(`DID Method not supported: "${did}".`)
   }
 
+  const [didUrl, hashFragment] = did.split('#')
+  // eslint-disable-next-line no-unused-vars
+  // const [didResource, query] = didUrl.split('?')
+
   // eslint-disable-next-line no-unused-vars
-  const [_did, _web, host, ...pathFragments] = did.split(':')
+  const [_did, _web, urlNoProtocol] = didUrl.split(':')
+
+  let parsedUrl
+  try {
+    // URI-decode the url (in case it contained a port number,
+    // for example, `did:web:localhost%3A8080`
+    parsedUrl = new URL('https://' + decodeURIComponent(urlNoProtocol))
+  } catch (error) {
+    throw new TypeError(`Cannot construct url from did: "${did}".`)
+  }
 
-  let pathname = ''
-  if (pathFragments.length === 0) {
-    pathname = '/.well-known/did.json'
+  if (!parsedUrl.pathname || parsedUrl.pathname === '/') {
+    parsedUrl.pathname = '/.well-known/did.json'
   } else {
-    pathname = '/' + pathFragments.map(decodeURIComponent).join('/')
+    const pathFragments = parsedUrl.pathname.split('/')
+    parsedUrl.pathname = pathFragments.map(decodeURIComponent).join('/')
+  }
+
+  if (hashFragment) {
+    parsedUrl.hash = hashFragment
+  }
+  return parsedUrl.toString()
+}
+
+/**
+ * Initializes the DID Document's keys/proof methods.
+ *
+ * @example
+ * didDocument.id = 'did:ex:123';
+ * const {didDocument, keyPairs} = await initKeys({
+ *   didDocument,
+ *   cryptoLd,
+ *   keyMap: {
+ *     capabilityInvocation: someExistingKey,
+ *     authentication: 'Ed25519VerificationKey2020',
+ *     assertionMethod: 'Ed25519VerificationKey2020',
+ *     keyAgreement: 'X25519KeyAgreementKey2019'
+ *   }
+ * });.
+ *
+ * @param {object} options - Options hashmap.
+ * @param {object} options.didDocument - DID Document.
+ * @typedef {object} CryptoLD
+ * @param {CryptoLD} [options.cryptoLd] - CryptoLD driver instance,
+ *   initialized with the key types this DID Document intends to support.
+ * @param {object} [options.keyMap] - Map of keys (or key types) by purpose.
+ *
+ * @returns {Promise<{didDocument: object, keyPairs: Map}>} Resolves with the
+ *   DID Document initialized with keys, as well as the map of the corresponding
+ *   key pairs (by key id).
+ */
+export async function initKeys ({ didDocument, cryptoLd, keyMap = {} } = {}) {
+  const doc = { ...didDocument }
+  if (!doc.id) {
+    throw new TypeError(
+      'DID Document "id" property is required to initialize keys.')
+  }
+
+  const keyPairs = new Map()
+
+  // Set the defaults for the created keys (if needed)
+  const options = { controller: doc.id }
+
+  for (const purpose in keyMap) {
+    if (!VERIFICATION_RELATIONSHIPS.has(purpose)) {
+      throw new Error(`Unsupported key purpose: "${purpose}".`)
+    }
+
+    let key
+    if (typeof keyMap[purpose] === 'string') {
+      if (!cryptoLd) {
+        throw new Error('Please provide an initialized CryptoLD instance.')
+      }
+      key = await cryptoLd.generate({ type: keyMap[purpose], ...options })
+    } else {
+      // An existing key has been provided
+      key = keyMap[purpose]
+    }
+
+    doc[purpose] = [key.export({ publicKey: true })]
+    keyPairs.set(key.id, key)
   }
 
-  return 'https://' + decodeURIComponent(host) + pathname
+  return { didDocument: doc, keyPairs }
 }
 
 export class DidWebResolver {
-  constructor ({ cryptoLd, keyMap = DEFAULT_KEY_MAP } = {}) {
-    this.method = 'web' // did:web:...
+  /**
+   * @param cryptoLd {CryptoLD}
+   * @param keyMap {object}
+   * @param [logger] {object} Logger object (with .log, .error, .warn,
+   *   etc methods).
+   */
+  constructor ({ cryptoLd, keyMap = DEFAULT_KEY_MAP, logger = console } = {}) {
+    this.method = 'web' // did:web:... (used for didIo resolver harness)
     this.cryptoLd = cryptoLd
     this.keyMap = keyMap
+    this.logger = logger
   }
 
   /**
    * Generates a new DID Document and initializes various authentication
    * and authorization proof purpose keys.
    *
-   * Usage:
-   * ```
+   * @example
    *   const url = 'https://example.com'
    *   const { didDocument, didKeys } = await didWeb.generate({url})
    *   didDocument.id
    *   // -> 'did:web:example.com'
-   * ```
+   *
    *
    * Either an `id` or a `url` is required:
    * @param [id] {string} - A did:web DID. If absent, will be converted from url
    * @param [url] {string}
    *
-   * @throws {Error}
+   * @param [keyMap=DEFAULT_KEY_MAP] {object} A hashmap of key types by purpose.
    *
-   * @returns {Promise<{didDocument: DidDocument, didKeys: object}>}
+   * @parma [cryptoLd] {object} CryptoLD instance with support for supported
+   *   crypto suites installed.
+   *
+   * @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 ({ id, url, keyMap = this.keyMap, cryptoLd = this.cryptoLd } = {}) {
-    const didDocument = new DidDocument({ id: id || didFromUrl({ url }) })
-    didDocument['@context'] = [DID_CONTEXT_URL]
+    const did = id || didFromUrl({ url })
+
+    // Compose the DID Document
+    let didDocument = {
+      '@context': [
+        didContext.constants.DID_CONTEXT_URL,
+        ed25519Context.constants.CONTEXT_URL,
+        x25519Context.constants.CONTEXT_URL
+      ],
+      id: did
+    }
+
+    const result = await initKeys({ didDocument, cryptoLd, keyMap })
+    const keyPairs = result.keyPairs
+    didDocument = result.didDocument
 
-    const { didKeys } = await didDocument.initKeys({ cryptoLd, keyMap })
-    return { didDocument, didKeys }
+    // Convenience function that returns the public/private key pair instance
+    // for a given purpose (authentication, assertionMethod, keyAgreement, etc).
+    const methodFor = ({ purpose }) => {
+      const { id: methodId } = didIo.findVerificationMethod({
+        doc: didDocument, purpose
+      })
+      return keyPairs.get(methodId)
+    }
+
+    return { didDocument, keyPairs, methodFor }
   }
 
   /**
    * Fetches a DID Document for a given DID.
-   * @param {string} did
    *
-   * @returns {Promise<DidDocument>}
+   * @example
+   * // In Node.js tests, use an agent to avoid self-signed certificate errors
+   * const agent = new https.agent({rejectUnauthorized: false});
+   *
+   * @param {string} [did] For example, 'did:web:example.com'
+   * @param {string} [url]
+   * @param {https.Agent} [agent] Optional agent used to customize network
+   *   behavior in Node.js (such as `rejectUnauthorized: false`).
+   * @param {object} [logger] Logger object (with .log, .error, .warn,
+   *   etc methods).
+   *
+   * @throws {Error}
+   *
+   * @returns {Promise<object>} Plain parsed JSON object of the DID Document.
    */
-  async get () {}
+  async get ({ did, url, agent, logger = this.logger }) {
+    const didUrl = url || urlFromDid({ did })
+    if (!didUrl) {
+      throw new TypeError('A DID or a URL is required.')
+    }
+
+    const [urlAuthority, keyIdFragment] = didUrl.split('#')
+
+    let didDocument
+    try {
+      logger.info(`Fetching "${urlAuthority}" via http client.`)
+      const result = await httpClient.get(urlAuthority, { agent })
+      didDocument = result.data
+    } catch (e) {
+      // status is HTTP status code
+      // data is JSON error from the server if available
+      const { data, status } = e
+      logger.error(`Http ${status} error:`, data)
+      throw e
+    }
+    if (didDocument && keyIdFragment) {
+      // resolve an individual key
+      // Keys are expected to have format: <did:web:...>#<keyIdFragment>
+      const didAuthority = didFromUrl({ url: urlAuthority })
+      const methodId = `${didAuthority}#${keyIdFragment}`
+
+      const key = didIo.findVerificationMethod({ doc: didDocument, methodId })
+      if (!key) {
+        throw new Error(`Key id ${methodId} not found.`)
+      }
+
+      const keyPair = await this.cryptoLd.from(key)
+
+      return keyPair.export({ publicKey: true, includeContext: true })
+    }
+
+    return didDocument
+  }
+
+  /**
+   * Returns the public key (verification method) object for a given DID
+   * Document and purpose. Useful in conjunction with a `.get()` call.
+   *
+   * @example
+   * const didDocument = await didKeyDriver.get({did});
+   * const authKeyData = didDriver.publicMethodFor({
+   *   didDocument, purpose: 'authentication'
+   * });
+   * // You can then create a suite instance object to verify signatures etc.
+   * const authPublicKey = await cryptoLd.from(authKeyData);
+   * const {verify} = authPublicKey.verifier();
+   *
+   * @param {object} options - Options hashmap.
+   * @param {object} options.didDocument - DID Document (retrieved via a
+   *   `.get()` or from some other source).
+   * @param {string} options.purpose - Verification method purpose, such as
+   *   'authentication', 'assertionMethod', 'keyAgreement' and so on.
+   *
+   * @returns {object} Returns the public key object (obtained from the DID
+   *   Document), without a `@context`.
+   */
+  publicMethodFor ({ didDocument, purpose } = {}) {
+    if (!didDocument) {
+      throw new TypeError('The "didDocument" parameter is required.')
+    }
+    if (!purpose) {
+      throw new TypeError('The "purpose" parameter is required.')
+    }
+
+    const method = didIo.findVerificationMethod({ doc: didDocument, purpose })
+    if (!method) {
+      throw new Error(`No verification method found for purpose "${purpose}"`)
+    }
+    return method
+  }
 }

package/src/index.js

@@ -1,3 +1,8 @@
-'use strict'
 
-export { DidWebResolver, didFromUrl, urlFromDid } from './DidWebResolver.js'
+import { DidWebResolver, didFromUrl, urlFromDid } from './DidWebResolver.js'
+
+const driver = options => {
+  return new DidWebResolver(options)
+}
+
+export { driver, DidWebResolver, didFromUrl, urlFromDid }

package/.idea/codeStyles/Project.xml

@@ -1,79 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <code_scheme name="Project" version="173">
-    <option name="LINE_SEPARATOR" value="&#10;" />
-    <option name="RIGHT_MARGIN" value="80" />
-    <JSCodeStyleSettings version="0">
-      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="false" />
-      <option name="FORCE_SEMICOLON_STYLE" value="true" />
-      <option name="SPACE_BEFORE_GENERATOR_MULT" value="true" />
-      <option name="USE_DOUBLE_QUOTES" value="false" />
-      <option name="FORCE_QUOTE_STYlE" value="true" />
-      <option name="OBJECT_LITERAL_WRAP" value="1" />
-      <option name="SPACES_WITHIN_OBJECT_LITERAL_BRACES" value="true" />
-      <option name="SPACES_WITHIN_IMPORTS" value="true" />
-    </JSCodeStyleSettings>
-    <DBN-PSQL>
-      <case-options enabled="true">
-        <option name="KEYWORD_CASE" value="lower" />
-        <option name="FUNCTION_CASE" value="lower" />
-        <option name="PARAMETER_CASE" value="lower" />
-        <option name="DATATYPE_CASE" value="lower" />
-        <option name="OBJECT_CASE" value="preserve" />
-      </case-options>
-      <formatting-settings enabled="false" />
-    </DBN-PSQL>
-    <DBN-SQL>
-      <case-options enabled="true">
-        <option name="KEYWORD_CASE" value="lower" />
-        <option name="FUNCTION_CASE" value="lower" />
-        <option name="PARAMETER_CASE" value="lower" />
-        <option name="DATATYPE_CASE" value="lower" />
-        <option name="OBJECT_CASE" value="preserve" />
-      </case-options>
-      <formatting-settings enabled="false">
-        <option name="STATEMENT_SPACING" value="one_line" />
-        <option name="CLAUSE_CHOP_DOWN" value="chop_down_if_statement_long" />
-        <option name="ITERATION_ELEMENTS_WRAPPING" value="chop_down_if_not_single" />
-      </formatting-settings>
-    </DBN-SQL>
-    <XML>
-      <option name="XML_LEGACY_SETTINGS_IMPORTED" value="true" />
-    </XML>
-    <codeStyleSettings language="CSS">
-      <indentOptions>
-        <option name="INDENT_SIZE" value="2" />
-        <option name="CONTINUATION_INDENT_SIZE" value="4" />
-        <option name="TAB_SIZE" value="2" />
-      </indentOptions>
-    </codeStyleSettings>
-    <codeStyleSettings language="HTML">
-      <indentOptions>
-        <option name="INDENT_SIZE" value="2" />
-        <option name="CONTINUATION_INDENT_SIZE" value="2" />
-        <option name="TAB_SIZE" value="2" />
-      </indentOptions>
-    </codeStyleSettings>
-    <codeStyleSettings language="Jade">
-      <indentOptions>
-        <option name="INDENT_SIZE" value="2" />
-        <option name="TAB_SIZE" value="2" />
-      </indentOptions>
-    </codeStyleSettings>
-    <codeStyleSettings language="JavaScript">
-      <option name="RIGHT_MARGIN" value="80" />
-      <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
-      <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
-      <option name="ALIGN_MULTILINE_FOR" value="false" />
-      <option name="SPACE_WITHIN_BRACKETS" value="true" />
-      <option name="SPACE_BEFORE_METHOD_PARENTHESES" value="true" />
-      <option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
-      <option name="KEEP_SIMPLE_BLOCKS_IN_ONE_LINE" value="true" />
-      <option name="KEEP_SIMPLE_METHODS_IN_ONE_LINE" value="true" />
-      <indentOptions>
-        <option name="INDENT_SIZE" value="2" />
-        <option name="CONTINUATION_INDENT_SIZE" value="2" />
-        <option name="TAB_SIZE" value="2" />
-      </indentOptions>
-    </codeStyleSettings>
-  </code_scheme>
-</component>

package/.idea/codeStyles/codeStyleConfig.xml

@@ -1,5 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <state>
-    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
-  </state>
-</component>