@abaxxtech/id 0.0.0

package/src/core/records-grant-authorization.ts

@@ -0,0 +1,167 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionsGrantMessage } from '../types/permissions-types.js';
+import type { RecordsPermissionScope } from '../types/permissions-grant-descriptor.js';
+import type { RecordsRead } from '../interfaces/records-read.js';
+import type { RecordsWriteMessage } from '../types/records-types.js';
+
+import { GrantAuthorization } from './grant-authorization.js';
+import { PermissionsConditionPublication } from '../types/permissions-grant-descriptor.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class RecordsGrantAuthorization {
+  /**
+   * Authorizes the given RecordsWrite in the scope of the DID given.
+   */
+  public static async authorizeWrite(
+    tenant: string,
+    incomingMessage: RecordsWriteMessage,
+    author: string,
+    permissionsGrantMessage: PermissionsGrantMessage,
+    messageStore: MessageStore,
+  ): Promise<void> {
+    await GrantAuthorization.authorizeGenericMessage(
+      tenant,
+      incomingMessage,
+      author,
+      permissionsGrantMessage,
+      messageStore
+    );
+
+    RecordsGrantAuthorization.verifyScope(incomingMessage, permissionsGrantMessage);
+
+    RecordsGrantAuthorization.verifyConditions(incomingMessage, permissionsGrantMessage);
+  }
+
+  /**
+   * Authorizes the scope of a PermissionsGrant for RecordsRead.
+   */
+  public static async authorizeRead(
+    tenant: string,
+    incomingMessage: RecordsRead,
+    newestRecordsWriteMessage: RecordsWriteMessage,
+    author: string,
+    permissionsGrantMessage: PermissionsGrantMessage,
+    messageStore: MessageStore,
+  ): Promise<void> {
+    await GrantAuthorization.authorizeGenericMessage(
+      tenant,
+      incomingMessage.message,
+      author,
+      permissionsGrantMessage,
+      messageStore
+    );
+
+    RecordsGrantAuthorization.verifyScope(newestRecordsWriteMessage, permissionsGrantMessage);
+  }
+
+  /**
+   * @param recordsWrite The source of the record being authorized. If the incoming message is a write,
+   *                     then this is the incoming RecordsWrite. Otherwise, it is the newest existing RecordsWrite.
+   */
+  private static verifyScope(
+    recordsWriteMessage: RecordsWriteMessage,
+    permissionsGrantMessage: PermissionsGrantMessage,
+  ): void {
+    const grantScope = permissionsGrantMessage.descriptor.scope as RecordsPermissionScope;
+
+    if (RecordsGrantAuthorization.isUnrestrictedScope(grantScope)) {
+      // scope has no restrictions beyond interface and method. Message is authorized to access any record.
+      return;
+    } else if (recordsWriteMessage.descriptor.protocol !== undefined) {
+      // authorization of protocol records must have grants that explicitly include the protocol
+      RecordsGrantAuthorization.authorizeProtocolRecord(recordsWriteMessage, grantScope);
+    } else {
+      RecordsGrantAuthorization.authorizeFlatRecord(recordsWriteMessage, grantScope);
+    }
+  }
+
+  /**
+   * Authorizes a grant scope for a protocol record
+   */
+  private static authorizeProtocolRecord(
+    recordsWriteMessage: RecordsWriteMessage,
+    grantScope: RecordsPermissionScope
+  ): void {
+    // Protocol records must have grants specifying the protocol
+    if (grantScope.protocol === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeNotProtocol,
+        'Grant for protocol record must specify protocol in its scope'
+      );
+    }
+
+    // The record's protocol must match the protocol specified in the record
+    if (grantScope.protocol !== recordsWriteMessage.descriptor.protocol) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeProtocolMismatch,
+        `Grant scope specifies different protocol than what appears in the record`
+      );
+    }
+
+    // If grant specifies either contextId, check that record is that context
+    if (grantScope.contextId !== undefined && grantScope.contextId !== recordsWriteMessage.contextId) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeContextIdMismatch,
+        `Grant scope specifies different contextId than what appears in the record`
+      );
+    }
+
+    // If grant specifies protocolPath, check that record is at that protocolPath
+    if (grantScope.protocolPath !== undefined && grantScope.protocolPath !== recordsWriteMessage.descriptor.protocolPath) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeProtocolPathMismatch,
+        `Grant scope specifies different protocolPath than what appears in the record`
+      );
+    }
+  }
+
+  /**
+   * Authorizes a grant scope for a non-protocol record
+   */
+  private static authorizeFlatRecord(
+    recordsWriteMessage: RecordsWriteMessage,
+    grantScope: RecordsPermissionScope
+  ): void {
+    if (grantScope.schema !== undefined) {
+      if (grantScope.schema !== recordsWriteMessage.descriptor.schema) {
+        throw new DwnError(
+          DwnErrorCode.RecordsGrantAuthorizationScopeSchema,
+          `Record does not have schema in PermissionsGrant scope with schema '${grantScope.schema}'`
+        );
+      }
+    }
+  }
+
+  /**
+   * Verifies grant `conditions`.
+   * Currently the only condition is `published` which only applies to RecordsWrites
+   */
+  private static verifyConditions(recordsWriteMessage: RecordsWriteMessage, permissionsGrantMessage: PermissionsGrantMessage): void {
+    const conditions = permissionsGrantMessage.descriptor.conditions;
+
+    // If conditions require publication, RecordsWrite must have `published` === true
+    if (conditions?.publication === PermissionsConditionPublication.Required && !recordsWriteMessage.descriptor.published) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationConditionPublicationRequired,
+        'PermissionsGrant requires message to be published'
+      );
+    }
+
+    // if conditions prohibit publication, RecordsWrite must have published === false or undefined
+    if (conditions?.publication === PermissionsConditionPublication.Prohibited && recordsWriteMessage.descriptor.published) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationConditionPublicationProhibited,
+        'PermissionsGrant prohibits message from being published'
+      );
+    }
+  }
+
+  /**
+   * Checks if scope has no restrictions beyond interface and method.
+   * Grant-holder is authorized to access any record.
+   */
+  private static isUnrestrictedScope(grantScope: RecordsPermissionScope): boolean {
+    return grantScope.protocol === undefined &&
+           grantScope.schema === undefined;
+  }
+}

package/src/core/tenant-gate.ts

@@ -0,0 +1,18 @@
+/**
+ * An interface that determines if a DID is a tenant of the DWN.
+ */
+export interface TenantGate {
+  /**
+   * @returns `true` if the given DID is a tenant of the DWN; `false` otherwise
+   */
+  isTenant(did: string): Promise<boolean>;
+}
+
+/**
+ * A tenant gate that treats every DID as a tenant.
+ */
+export class AllowAllTenantGate implements TenantGate {
+  public async isTenant(_did: string): Promise<boolean> {
+    return true;
+  }
+}

package/src/did/did-dht-resolver.ts

@@ -0,0 +1,241 @@
+import dnsPacket from 'dns-packet';
+import { ed25519 } from '../jose/algorithms/signing/ed25519.js';
+import type { PublicJwk } from '../types/jose-types.js';
+import { Secp256k1 } from '../utils/secp256k1.js';
+import type { DidDocument, DidMethodResolver, DidResolutionResult } from '../types/did-types.js';
+
+
+/**
+ * did:dht Resolver.
+ * Resolves DIDs using the Pkarr DHT network.
+ *
+ * Helpful Resources:
+ * * [DID-DHT Spec](https://did-dht.com/)
+ */
+export class DidDhtResolver implements DidMethodResolver {
+  private pkarrRelay: string;
+
+  constructor(pkarrRelay: string = DidDhtResolver.defaultRelayUrl()) {
+    this.pkarrRelay = pkarrRelay;
+  }
+
+  method(): string {
+    return 'dht';
+  }
+
+  async resolve(did: string): Promise<DidResolutionResult> {
+    const [_scheme, _method, id] = did.split(':', 3);
+
+    try {
+      // Fetch the DHT packet from the Pkarr relay
+      const response = await fetch(`${this.pkarrRelay}/${id}`);
+
+      if (!response.ok) {
+        // DID not found in DHT
+        return {
+          '@context'            : 'https://w3id.org/did-resolution/v1',
+          didDocument           : undefined,
+          didDocumentMetadata   : {},
+          didResolutionMetadata : {
+            error: `DID ${did} not found in DHT`
+          }
+        };
+      }
+
+      // Parse the response body as the DNS packet
+      const packetBytes = new Uint8Array(await response.arrayBuffer());
+
+      // Convert DNS packet to DID Document
+      const didDocument = await this.fromDnsPacket(did, packetBytes);
+
+      return {
+        '@context'            : 'https://w3id.org/did-resolution/v1',
+        didDocument,
+        didDocumentMetadata   : {},
+        didResolutionMetadata : {
+          contentType: 'application/did+json',
+        }
+      };
+    } catch (error: any) {
+      return {
+        '@context'            : 'https://w3id.org/did-resolution/v1',
+        didDocument           : undefined,
+        didDocumentMetadata   : {},
+        didResolutionMetadata : {
+          error: `Error resolving DID ${did}: ${error.message}`
+        }
+      };
+    }
+  }
+
+  /**
+   * Converts a signed pkarr relay payload (`sig + seq + dns-packet`) into a DID Document.
+   */
+  private async fromDnsPacket(did: string, packetBytes: Uint8Array): Promise<DidDocument> {
+    const rawDnsPacket = this.extractRawDnsPacket(packetBytes);
+    const decoded = dnsPacket.decode(Buffer.from(rawDnsPacket)) as any;
+    const answers = Array.isArray(decoded.answers) ? decoded.answers : [];
+
+    const didDocument: DidDocument = {
+      '@context': [
+        'https://www.w3.org/ns/did/v1',
+        'https://w3id.org/security/suites/jws-2020/v1'
+      ],
+      id                 : did,
+      verificationMethod : []
+    };
+
+    const keyLookup = new Map<string, string>();
+    let rootRecordData: string | undefined;
+
+    for (const answer of answers) {
+      if (answer.type !== 'TXT') {continue;}
+      const recordName = String(answer.name || '').toLowerCase();
+      const recordData = this.txtToString(answer.data);
+      const head = this.recordHead(recordName);
+      if (!recordData || !head) {continue;}
+
+      if (head.type === 'k') {
+        const parsed = this.parseTxtRecord(recordData);
+        const keyId = parsed.id;
+        const keyType = parsed.t;
+        const keyMaterial = parsed.k;
+        if (!keyId || !keyType || !keyMaterial) {continue;}
+
+        const publicJwk = await this.keyMaterialToJwk(keyType, keyId, keyMaterial);
+        didDocument.verificationMethod!.push({
+          id           : `${did}#${keyId}`,
+          type         : 'JsonWebKey2020',
+          controller   : did,
+          publicKeyJwk : publicJwk
+        });
+
+        keyLookup.set(head.identifier, `#${keyId}`);
+        continue;
+      }
+
+      if (head.type === 's') {
+        const parsed = this.parseTxtRecord(recordData);
+        const serviceId = parsed.id;
+        const serviceType = parsed.t;
+        const serviceUri = parsed.uri;
+        if (!serviceId || !serviceType || !serviceUri) {continue;}
+
+        didDocument.service ??= [];
+        didDocument.service.push({
+          id              : `${did}#${serviceId}`,
+          type            : serviceType,
+          serviceEndpoint : serviceUri
+        });
+        continue;
+      }
+
+      if (head.type === 'did') {
+        rootRecordData = recordData;
+      }
+    }
+
+    if (rootRecordData) {
+      for (const segment of rootRecordData.split(';')) {
+        const [relationship, refsRaw] = segment.split('=');
+        if (!relationship || !refsRaw) {continue;}
+
+        const refs = refsRaw.split(',')
+          .map((value) => keyLookup.get(value.trim()))
+          .filter((value): value is string => Boolean(value));
+
+        if (!refs.length) {continue;}
+
+        switch (relationship) {
+        case 'auth':
+          didDocument.authentication = refs;
+          break;
+        case 'asm':
+          didDocument.assertionMethod = refs;
+          break;
+        case 'agm':
+          didDocument.keyAgreement = refs;
+          break;
+        case 'inv':
+          didDocument.capabilityInvocation = refs;
+          break;
+        case 'del':
+          didDocument.capabilityDelegation = refs;
+          break;
+        default:
+          break;
+        }
+      }
+    }
+
+    return didDocument;
+  }
+
+  private extractRawDnsPacket(packetBytes: Uint8Array): Uint8Array {
+    if (packetBytes.length > 72) {
+      return packetBytes.slice(72);
+    }
+    return packetBytes;
+  }
+
+  private txtToString(data: unknown): string {
+    if (typeof data === 'string') {return data;}
+    if (Array.isArray(data)) {
+      return data.map((chunk) => this.txtToString(chunk)).join('');
+    }
+    if (data instanceof Uint8Array) {
+      return Buffer.from(data).toString('utf8');
+    }
+    return '';
+  }
+
+  private parseTxtRecord(data: string): Record<string, string> {
+    return data.split(',').reduce((acc, pair) => {
+      const [key, value] = pair.split('=');
+      if (!key || value === undefined) {return acc;}
+      acc[key.trim()] = value.trim();
+      return acc;
+    }, {} as Record<string, string>);
+  }
+
+  private recordHead(recordName: string): { type: 'k' | 's' | 'did', identifier: string } | null {
+    const firstLabel = recordName.split('.')[0] ?? '';
+    if (firstLabel === '_did') {
+      return { type: 'did', identifier: 'did' };
+    }
+    if (firstLabel.startsWith('_k')) {
+      return { type: 'k', identifier: firstLabel.slice(1) };
+    }
+    if (firstLabel.startsWith('_s')) {
+      return { type: 's', identifier: firstLabel.slice(1) };
+    }
+    return null;
+  }
+
+  private async keyMaterialToJwk(keyType: string, keyId: string, keyBase64Url: string): Promise<PublicJwk> {
+    const keyBytes = this.base64UrlToBytes(keyBase64Url);
+    if (keyType === '0') {
+      const publicJwk = await ed25519.publicKeyToJwk(keyBytes);
+      publicJwk.kid = keyId;
+      return publicJwk;
+    }
+    if (keyType === '1') {
+      const publicJwk = await Secp256k1.publicKeyToJwk(keyBytes);
+      publicJwk.kid = keyId;
+      return publicJwk;
+    }
+    throw new Error(`Unsupported did:dht key type: ${keyType}`);
+  }
+
+  private base64UrlToBytes(value: string): Uint8Array {
+    const pad = value.length % 4 === 0 ? '' : '='.repeat(4 - (value.length % 4));
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/') + pad;
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+
+  private static defaultRelayUrl(): string {
+    const envRelayUrl = typeof process !== 'undefined' ? process.env.DHT_RELAY_URL?.trim() : undefined;
+    return envRelayUrl || 'http://localhost:8085/dht';
+  }
+}
+

package/src/did/did-ion-resolver.ts

@@ -0,0 +1,52 @@
+import type { DidMethodResolver, DidResolutionResult } from '../types/did-types.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+import crossFetch from 'cross-fetch';
+// supports fetch in: node, browsers, and browser extensions.
+// uses native fetch if available in environment or falls back to a ponyfill.
+// 'cross-fetch' is a ponyfill that uses `XMLHTTPRequest` under the hood.
+// `XMLHTTPRequest` cannot be used in browser extension background service workers.
+// browser extensions get even more strict with `fetch` in that it cannot be referenced
+// indirectly.
+const defaultFetch = globalThis.fetch ?? crossFetch;
+
+/**
+ * Resolver for ION DIDs.
+ *
+ * NOTE: For production use, consider using ion-sidtree in a Docker container
+ * to resolve ION DIDs locally instead of relying on external resolution endpoints.
+ * This would provide better reliability and performance.
+ */
+export class DidIonResolver implements DidMethodResolver {
+  private fetchFn: typeof globalThis.fetch;
+
+  /**
+   * @param resolutionEndpoint optional custom URL to send DID resolution request to
+   * @param fetchFn optional custom fetch function for testing
+   */
+  constructor (
+    private resolutionEndpoint: string = 'https://discover.did.msidentity.com/1.0/identifiers/',
+    fetchFn?: typeof globalThis.fetch
+  ) {
+    this.fetchFn = fetchFn ?? defaultFetch;
+  }
+
+  method(): string {
+    return 'ion';
+  }
+
+  async resolve(did: string): Promise<DidResolutionResult> {
+    // using `URL` constructor to handle both existence and absence of trailing slash '/' in resolution endpoint
+    // appending './' to DID so 'did' in 'did:ion:abc' doesn't get interpreted as a URL scheme (e.g. like 'http') due to the colon
+    const resolutionUrl = new URL('./' + did, this.resolutionEndpoint).toString();
+    const response = await this.fetchFn(resolutionUrl);
+
+    if (response.status !== 200) {
+      throw new DwnError(DwnErrorCode.DidResolutionFailed, `unable to resolve ${did}, got http status ${response.status}`);
+    }
+
+    const didResolutionResult = await response.json();
+    return didResolutionResult;
+  }
+
+}

package/src/did/did-key-resolver.ts

@@ -0,0 +1,137 @@
+import varint from 'varint';
+import type { DidDocument, DidMethodResolver, DidResolutionResult } from '../types/did-types.js';
+
+import { base58btc } from 'multiformats/bases/base58';
+import { Did } from './did.js';
+import { ed25519 } from '../../src/jose/algorithms/signing/ed25519.js';
+import { Encoder } from '../utils/encoder.js';
+import { Secp256k1 } from '../utils/secp256k1.js';
+import type { KeyMaterial, PublicJwk } from '../types/jose-types.js';
+
+/**
+ * did:key Resolver.
+ * * **NOTE**: Key support is limited to Ed25519 and SECP256k1.
+ * * **NOTE**: `verificationMethod` support is limited to `JsonWebKey2020`
+ *
+ * Helpful Resources:
+ * * [DID-Key Draft Spec](https://w3c-ccg.github.io/did-method-key/)
+ */
+export class DidKeyResolver implements DidMethodResolver {
+  method(): string {
+    return 'key';
+  }
+
+  /**
+   * Gets the number of bytes of the multicodec header in the `did:key` DID.
+   * @param did - A `did:key` DID
+   * @returns size of the multicodec head in number of bytes
+   */
+  public static getMulticodecSize(did: Uint8Array): number {
+    let multicodecHeaderSize = 0;
+
+    while (true) {
+      const currentByte = did[multicodecHeaderSize];
+      multicodecHeaderSize++;
+
+      // bitwise and with binary 1000 0000
+      // as soon as the result byte does not lead with a leading 1, we've reached the end of the multicodec header
+      if ((currentByte & 0x80) !== 0x80) {
+        break;
+      }
+    }
+
+    return multicodecHeaderSize;
+  }
+
+  async resolve(did: string): Promise<DidResolutionResult> {
+    const [_scheme, _method, id] = did.split(':', 3);
+
+    try {
+      const idBytes = base58btc.decode(id);
+      const multicodec = varint.decode(idBytes);
+      const multicodecSize = DidKeyResolver.getMulticodecSize(idBytes);
+      const publicKeyBytes = idBytes.slice(multicodecSize);
+
+      // key specific values
+      const keySpecificContext: string[] = [];
+      let publicJwk: PublicJwk;
+      if (multicodec === 0xed) {
+        // ed25519-pub multicodec
+        keySpecificContext.push('https://w3id.org/security/suites/ed25519-2020/v1');
+        publicJwk = await ed25519.publicKeyToJwk(publicKeyBytes);
+      } else if (multicodec === 0xe7) {
+        // secp256k1-pub multicodec
+        publicJwk = await Secp256k1.publicKeyToJwk(publicKeyBytes);
+      } else {
+        throw Error(`key type of multicodec ${multicodec} is not supported`);
+      }
+
+      const keyId = `${did}#${id}`;
+
+      const didDocument: DidDocument = {
+        '@context': [
+          'https://www.w3.org/ns/did/v1',
+          'https://w3id.org/security/suites/jws-2020/v1',
+          ...keySpecificContext
+        ],
+        'id'                 : did,
+        'verificationMethod' : [{
+          id           : keyId,
+          type         : 'JsonWebKey2020',
+          controller   : did,
+          publicKeyJwk : publicJwk
+        }],
+        'authentication'       : [keyId],
+        'assertionMethod'      : [keyId],
+        'capabilityDelegation' : [keyId],
+        'capabilityInvocation' : [keyId]
+      };
+
+      return {
+        '@context'            : 'https://w3id.org/did-resolution/v1',
+        didDocument,
+        didDocumentMetadata   : {},
+        didResolutionMetadata : {}
+      };
+    } catch {
+      return {
+        didDocument           : undefined,
+        didDocumentMetadata   : {},
+        didResolutionMetadata : {
+          error: 'invalidDid'
+        },
+      };
+    }
+  }
+
+  /**
+   * Generates a new ed25519 public/private key pair. Creates a DID using the private key.
+   * @returns DID and its key material.
+   */
+  public static async generate(): Promise<{ did: string } & KeyMaterial> {
+    const { publicJwk, privateJwk } = await ed25519.generateKeyPair();
+
+    // multicodec code for Ed25519 public keys
+    const ed25519Multicodec = varint.encode(0xed);
+    const publicKeyBytes = Encoder.base64UrlToBytes(publicJwk.x);
+    const idBytes = new Uint8Array(ed25519Multicodec.length + publicKeyBytes.byteLength);
+    idBytes.set(ed25519Multicodec, 0);
+    idBytes.set(publicKeyBytes, ed25519Multicodec.length);
+
+    const id = base58btc.encode(idBytes);
+    const did = `did:key:${id}`;
+    const keyId = DidKeyResolver.getKeyId(did);
+
+    return { did, keyId, keyPair: { publicJwk, privateJwk } };
+  }
+
+  /**
+   * Gets the fully qualified key ID of a `did:key` DID. ie. '<did>#<method-specific-id>'
+   */
+  public static getKeyId(did: string): string {
+    const methodSpecificId = Did.getMethodSpecificId(did);
+    const keyId = `${did}#${methodSpecificId}`;
+    return keyId;
+  };
+
+}

package/src/did/did-resolver.ts

@@ -0,0 +1,77 @@
+import type { Cache } from '../types/cache.js';
+import type { DidMethodResolver, DidResolutionResult } from '../types/did-types.js';
+
+import { Did } from './did.js';
+import { DidDhtResolver } from './did-dht-resolver.js';
+import { DidIonResolver } from './did-ion-resolver.js';
+import { DidKeyResolver } from './did-key-resolver.js';
+import { MemoryCache } from '../utils/memory-cache.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+/**
+ * A DID resolver that by default supports `did:key`, `did:ion`, and `did:dht` DIDs.
+ */
+export class DidResolver {
+  private didResolvers: Map<string, DidMethodResolver>;
+  private cache: Cache;
+
+  constructor(resolvers?: DidMethodResolver[], cache?:Cache) {
+
+    this.cache = cache || new MemoryCache(600);
+
+    // construct default DID method resolvers if none given
+    if (resolvers === undefined || resolvers.length === 0) {
+      resolvers = [
+        new DidIonResolver(),
+        new DidKeyResolver(),
+        new DidDhtResolver()
+      ];
+    }
+
+    this.didResolvers = new Map();
+
+    for (const resolver of resolvers) {
+      this.didResolvers.set(resolver.method(), resolver);
+    }
+  }
+
+  /**
+   * attempt to resolve the DID provided
+   * @throws {Error} if DID is invalid
+   * @throws {Error} if DID method is not supported
+   * @throws {Error} if resolving DID fails
+   * @param did - the DID to resolve
+   * @returns {DidResolutionResult}
+   */
+  public async resolve(did: string): Promise<DidResolutionResult> {
+    // naively validate the given DID
+    Did.validate(did);
+    const splitDID = did.split(':', 3);
+
+    const didMethod = splitDID[1];
+    const didResolver = this.didResolvers.get(didMethod);
+
+    if (!didResolver) {
+      throw new DwnError(DwnErrorCode.DidMethodNotSupported, `${didMethod} DID method not supported`);
+    }
+
+    // use cached result if exists
+    const cachedResolutionResult = await this.cache.get(did);
+    const resolutionResult = cachedResolutionResult ?? await didResolver.resolve(did);
+    if (cachedResolutionResult === undefined){
+      await this.cache.set(did, resolutionResult);
+    }
+
+    const { didDocument, didResolutionMetadata } = resolutionResult;
+
+    if (!didDocument || didResolutionMetadata?.error) {
+      const { error } = didResolutionMetadata;
+      let errMsg = `Failed to resolve DID ${did}.`;
+      errMsg += error ? ` Error: ${error}` : '';
+
+      throw new DwnError(DwnErrorCode.DidResolutionFailed, errMsg);
+    }
+
+    return resolutionResult;
+  }
+}