simplify agent-did-resolver-cache abstraction

audit-ci.json

@@ -6,6 +6,7 @@
     "mysql2",
     "braces",
     "GHSA-rv95-896h-c2vc",
-    "GHSA-952p-6rrq-rcjv"
+    "GHSA-952p-6rrq-rcjv",
+    "GHSA-4vvj-4cpr-p986"
   ]
 }

packages/agent/src/agent-did-resolver-cache.ts

@@ -2,10 +2,21 @@ import { DidResolutionResult, DidResolverCache, DidResolverCacheLevel, DidResolv
 import { Web5PlatformAgent } from './types/agent.js';
 
 
+/**
+ * AgentDidResolverCache keeps a stale copy of the Agent's managed Identity DIDs and only evicts and refreshes upon a successful resolution.
+ * This allows for quick and offline access to the internal DIDs used by the agent.
+ */
 export class AgentDidResolverCache extends DidResolverCacheLevel implements DidResolverCache {
 
+  /**
+   * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
+   * the `AgentDidApi`. This agent is used to interact with other Web5 agent components. It's vital
+   * to ensure this instance is set to correctly contextualize operations within the broader Web5
+   * Agent framework.
+   */
   private _agent?: Web5PlatformAgent;
 
+  /** A map of DIDs that are currently in-flight. This helps avoid going into an infinite loop */
   private _resolving: Map<string, boolean> = new Map();
 
   constructor({ agent, db, location, ttl }: DidResolverCacheLevelParams & { agent?: Web5PlatformAgent }) {

packages/agent/src/did-api.ts

@@ -8,10 +8,6 @@ import type {
   DidResolutionResult,
   DidResolutionOptions,
   DidVerificationMethod,
-  DidUrlDereferencer,
-  DidResolver,
-  DidDereferencingOptions,
-  DidDereferencingResult,
   DidResolverCache,
 } from '@web5/dids';
 
@@ -88,9 +84,13 @@ export interface DidApiParams {
   agent?: Web5PlatformAgent;
 
   /**
-   * An optional `AgentDidResolverCache` instance used for caching resolved DID documents.
+   * An optional `DidResolverCache` instance used for caching resolved DID documents.
    *
-   * If omitted, the default LevelDB and parameters are used to create a new cache instance.
+   * Providing a cache implementation can significantly enhance resolution performance by avoiding
+   * redundant resolutions for previously resolved DIDs. If omitted, the default is an instance of `AgentDidResolverCache`.
+   *
+   * `AgentDidResolverCache` keeps a stale copy of the Agent's managed Identity DIDs and only refreshes upon a successful resolution.
+   * This allows for quick and offline access to the internal DIDs used by the agent.
    */
   resolverCache?: DidResolverCache;
 
@@ -103,7 +103,7 @@ export function isDidRequest<T extends DidInterface>(
   return didRequest.messageType === messageType;
 }
 
-export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager> implements DidResolver, DidUrlDereferencer {
+export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager> extends UniversalResolver {
   /**
    * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
    * the `AgentDidApi`. This agent is used to interact with other Web5 agent components. It's vital
@@ -112,24 +112,20 @@ export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager>
    */
   private _agent?: Web5PlatformAgent;
 
-  private _cache: DidResolverCache;
-
   private _didMethods: Map<string, DidMethodApi> = new Map();
 
-  private _resolver: UniversalResolver;
-
   private _store: AgentDataStore<PortableDid>;
 
   constructor({ agent, didMethods, resolverCache, store }: DidApiParams) {
     if (!didMethods) {
       throw new TypeError(`AgentDidApi: Required parameter missing: 'didMethods'`);
     }
 
-    this._cache = resolverCache ?? new AgentDidResolverCache({ location: 'DATA/AGENT/DID_CACHE' });
-
-    this._resolver = new UniversalResolver({
-      cache        : this._cache,
-      didResolvers : didMethods
+    // Initialize the DID resolver with the given DID methods and resolver cache, or use a default
+    // AgentDidResolverCache if none is provided.
+    super({
+      didResolvers : didMethods,
+      cache        : resolverCache ?? new AgentDidResolverCache({ agent, location: 'DATA/AGENT/DID_CACHE' })
     });
 
     this._agent = agent;
@@ -160,8 +156,8 @@ export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager>
     this._agent = agent;
 
     // AgentDidResolverCache should set the agent if it is the type of cache being used
-    if ('agent' in this._cache) {
-      this._cache.agent = agent;
+    if ('agent' in this.cache) {
+      this.cache.agent = agent;
     }
   }
 
@@ -353,14 +349,6 @@ export class AgentDidApi<TKeyManager extends AgentKeyManager = AgentKeyManager>
     throw new Error(`AgentDidApi: Unsupported request type: ${request.messageType}`);
   }
 
-  public async resolve(didUri: string, options?: DidResolutionOptions): Promise<DidResolutionResult> {
-    return this._resolver.resolve(didUri, options);
-  }
-
-  public async dereference(didUrl: string, options?: DidDereferencingOptions): Promise<DidDereferencingResult> {
-    return this._resolver.dereference(didUrl);
-  }
-
   private getMethod(methodName: string): DidMethodApi {
     const didMethodApi = this._didMethods.get(methodName);