@enbox/dids 0.0.1

package/src/methods/did-method.ts

@@ -0,0 +1,276 @@
+import type {
+  CryptoApi,
+  LocalKeyManager,
+  InferKeyGeneratorAlgorithm,
+} from '@enbox/crypto';
+
+import type { BearerDid } from '../bearer-did.js';
+import type { DidMetadata } from '../types/portable-did.js';
+import type {
+  DidDocument,
+  DidResolutionResult,
+  DidResolutionOptions,
+  DidVerificationMethod,
+} from '../types/did-core.js';
+
+import { DidVerificationRelationship } from '../types/did-core.js';
+
+/**
+ * Represents options during the creation of a Decentralized Identifier (DID).
+ *
+ * Implementations of this interface may contain properties and methods that provide specific
+ * options or metadata during the DID creation processes following specific DID method
+ * specifications.
+ */
+export interface DidCreateOptions<TKms> {
+  /**
+   * Optional. An array of verification methods to be included in the DID document.
+   */
+  verificationMethods?: DidCreateVerificationMethod<TKms>[];
+}
+
+/**
+ * Options for additional verification methods added to the DID Document during the creation of a
+ * new Decentralized Identifier (DID).
+ */
+export interface DidCreateVerificationMethod<TKms> extends Pick<Partial<DidVerificationMethod>, 'controller' | 'id' | 'type'> {
+  /**
+   * The name of the cryptographic algorithm to be used for key generation.
+   *
+   * Examples might include `Ed25519` and `ES256K` but will vary depending on the DID method
+   * specification and the key management system in use.
+   *
+   * @example
+   * ```ts
+   * const verificationMethod: DidCreateVerificationMethod = {
+   *   algorithm: 'Ed25519'
+   * };
+   * ```
+   */
+  algorithm: TKms extends CryptoApi
+    ? InferKeyGeneratorAlgorithm<TKms>
+    : InferKeyGeneratorAlgorithm<LocalKeyManager>;
+
+  /**
+   * Optionally specify the purposes for which a verification method is intended to be used in a DID
+   * document.
+   *
+   * The `purposes` property defines the specific
+   * {@link DidVerificationRelationship | verification relationships} between the DID subject and
+   * the verification method. This enables the verification method to be utilized for distinct
+   * actions such as authentication, assertion, key agreement, capability delegation, and others. It
+   * is important for verifiers to recognize that a verification method must be associated with the
+   * relevant purpose in the DID document to be valid for that specific use case.
+   *
+   * @example
+   * ```ts
+   * const verificationMethod: DidCreateVerificationMethod = {
+   *   algorithm: 'Ed25519',
+   *   controller: 'did:example:1234',
+   *   purposes: ['authentication', 'assertionMethod']
+   * };
+   * ```
+   */
+  purposes?: (DidVerificationRelationship | keyof typeof DidVerificationRelationship)[];
+}
+
+/**
+ * Defines the API for a specific DID method. It includes functionalities for creating and resolving
+ * DIDs.
+ *
+ * @typeparam T - The type of the DID instance associated with this method.
+ * @typeparam O - The type of the options used for creating the DID.
+ */
+export interface DidMethodApi<
+    TKms extends CryptoApi | undefined = CryptoApi,
+    TDid extends BearerDid = BearerDid,
+    TOptions extends DidCreateOptions<TKms> = DidCreateOptions<TKms>
+  > extends DidMethodResolver {
+  /**
+   * The name of the DID method.
+   *
+   * For example, in the DID `did:example:123456`, "example" would be the method name.
+   */
+  methodName: string;
+
+  new (): DidMethod;
+
+  /**
+   * Creates a new DID.
+   *
+   * This function should generate a new DID in accordance with the DID method specification being
+   * implemented, using the provided `keyManager`, and optionally, any provided `options`.
+   *
+   * @param params - The parameters used to create the DID.
+   * @param params.keyManager - Optional. The cryptographic API used for key management.
+   * @param params.options - Optional. The options used for creating the DID.
+   * @returns A promise that resolves to the newly created DID instance.
+   */
+  create(params: {
+    keyManager?: TKms;
+    options?: TOptions;
+  }): Promise<TDid>;
+
+  /**
+   * Given a DID Document, return the verification method that will be used for signing messages and
+   * credentials.
+   *
+   * If given, the `methodId` parameter is used to select the verification method. If not given, a
+   * DID method specific approach is taken to selecting the verification method to return.
+   *
+   * @param params - The parameters for the `getSigningMethod` operation.
+   * @param params.didDocument - DID Document to get the verification method from.
+   * @param params.methodId - ID of the verification method to use for signing.
+   * @returns A promise that resolves to the erification method to use for signing.
+   */
+  getSigningMethod(params: {
+    didDocument: DidDocument;
+    methodId?: string;
+  }): Promise<DidVerificationMethod>;
+}
+
+/**
+ * Defines the interface for resolving a DID using a specific DID method.
+ *
+ * A DID resolver takes a DID URI as input and returns a {@link DidResolutionResult} object.
+ *
+ * @property {string} methodName - The name of the DID method.
+ * @method resolve - Asynchronous method to resolve a DID URI. Takes the DID URI and optional resolution options.
+ */
+export interface DidMethodResolver {
+  /**
+   * The name of the DID method.
+   *
+   * For example, in the DID `did:example:123456`, "example" would be the method name.
+   */
+  methodName: string;
+
+  new (): DidMethod;
+
+  /**
+   * Resolves a DID URI.
+   *
+   * This function should resolve the DID URI in accordance with the DID method specification being
+   * implemented, using the provided `options`.
+   *
+   * @param didUri - The DID URI to be resolved.
+   * @param options - Optional. The options used for resolving the DID.
+   * @returns A {@link DidResolutionResult} object containing the DID document and metadata or an error.
+   */
+  resolve(didUri: string, options?: DidResolutionOptions): Promise<DidResolutionResult>;
+}
+
+/**
+ * Represents the result of a Decentralized Identifier (DID) registration operation.
+ *
+ * This type encapsulates the complete outcome of registering a DID, including the registration
+ * metadata, the DID document (if registration is successful), and metadata about the DID document.
+ */
+export interface DidRegistrationResult {
+  /**
+   * The DID document resulting from the registration process, if successful.
+   *
+   * If the registration operation was successful, this MUST contain a DID document
+   * corresponding to the DID. If the registration is unsuccessful, this value MUST be empty.
+   *
+   * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocument | DID Core Specification, § DID Document}
+   */
+  didDocument: DidDocument | null;
+
+  /**
+   * Metadata about the DID Document.
+   *
+   * This structure contains information about the DID Document like creation and update timestamps,
+   * deactivation status, versioning information, and other details relevant to the DID Document.
+   *
+   * @see {@link https://www.w3.org/TR/did-core/#dfn-diddocumentmetadata | DID Core Specification, § DID Document Metadata}
+   */
+  didDocumentMetadata: DidMetadata;
+
+  /**
+   * A metadata structure consisting of values relating to the results of the DID registration
+   * process.
+   *
+   * This structure is REQUIRED, and in the case of an error in the registration process,
+   * this MUST NOT be empty. If the registration is not successful, this structure MUST contain an
+   * `error` property describing the error.
+   */
+  didRegistrationMetadata: DidRegistrationMetadata;
+}
+
+/**
+ * Represents metadata related to the result of a DID registration operation.
+ *
+ * This type includes fields that provide information about the outcome of a DID registration
+ * process (e.g., create, update, deactivate), including any errors that occurred.
+ *
+ * This metadata typically changes between invocations of the `create`, `update`, and `deactivate`
+ * functions, as it represents data about the registration process itself.
+ */
+export type DidRegistrationMetadata = {
+  /**
+   * An error code indicating issues encountered during the DID registration process.
+   *
+   * While the DID Core specification does not define a specific set of error codes for the result
+   * returned by the `create`, `update`, or `deactivate` functions, it is recommended to use the
+   * error codes defined in the DID Specification Registries for
+   * {@link https://www.w3.org/TR/did-spec-registries/#error | DID Resolution Metadata }.
+   *
+   * Recommended error codes include:
+   *   - `internalError`: An unexpected error occurred during DID registration process.
+   *   - `invalidDid`: The provided DID is invalid.
+   *   - `invalidDidDocument`: The provided DID document does not conform to valid syntax.
+   *   - `invalidDidDocumentLength`: The byte length of the provided DID document does not match the expected value.
+   *   - `invalidSignature`: Verification of a signature failed.
+   *   - `methodNotSupported`: The DID method specified is not supported.
+   *   - Custom error codes can also be provided as strings.
+   */
+  error?: string;
+
+  // Additional output metadata generated during DID registration.
+  [key: string]: any;
+};
+
+/**
+ * Base abstraction for all Decentralized Identifier (DID) method implementations.
+ *
+ * This base class serves as a foundational structure upon which specific DID methods
+ * can be implemented. Subclasses should furnish particular method and data models adherent
+ * to various DID methods, taking care to adhere to the
+ * {@link https://www.w3.org/TR/did-core/ | W3C DID Core specification} and the
+ * respective DID method specifications.
+ */
+export class DidMethod {
+  /**
+   * MUST be implemented by all DID method implementations that extend {@link DidMethod}.
+   *
+   * Given the W3C DID Document of a DID, return the verification method that will be used for
+   * signing messages and credentials. If given, the `methodId` parameter is used to select the
+   * verification method. If not given, each DID method implementation will select a default
+   * verification method from the DID Document.
+   *
+   * @param _params - The parameters for the `getSigningMethod` operation.
+   * @param _params.didDocument - DID Document to get the verification method from.
+   * @param _params.methodId - ID of the verification method to use for signing.
+   * @returns Verification method to use for signing.
+   */
+  public static async getSigningMethod(_params: {
+    didDocument: DidDocument;
+    methodId?: string;
+  }): Promise<DidVerificationMethod | undefined> {
+    throw new Error(`Not implemented: Classes extending DidMethod must implement getSigningMethod()`);
+  }
+
+  /**
+   * MUST be implemented by all DID method implementations that extend {@link DidMethod}.
+   *
+   * Resolves a DID URI to a DID Document.
+   *
+   * @param _didUri - The DID to be resolved.
+   * @param _options - Optional parameters for resolving the DID.
+   * @returns A Promise resolving to a {@link DidResolutionResult} object representing the result of the resolution.
+   */
+  public static async resolve(_didUri: string, _options?: DidResolutionOptions): Promise<DidResolutionResult> {
+    throw new Error(`Not implemented: Classes extending DidMethod must implement resolve()`);
+  }
+}

package/src/methods/did-web.ts

@@ -0,0 +1,96 @@
+import type { DidDocument, DidResolutionOptions, DidResolutionResult } from '../types/did-core.js';
+
+import { Did } from '../did.js';
+import { DidMethod } from './did-method.js';
+import { EMPTY_DID_RESOLUTION_RESULT } from '../types/did-resolution.js';
+
+/**
+ * The `DidWeb` class provides an implementation of the `did:web` DID method.
+ *
+ * Features:
+ * - DID Resolution: Resolve a `did:web` to its corresponding DID Document.
+ *
+ * @remarks
+ * The `did:web` method uses a web domain's existing reputation and aims to integrate decentralized
+ * identities with the existing web infrastructure to drive adoption. It leverages familiar web
+ * security models and domain ownership to provide accessible, interoperable digital identity
+ * management.
+ *
+ * @see {@link https://w3c-ccg.github.io/did-method-web/ | DID Web Specification}
+ *
+ * @example
+ * ```ts
+ * // DID Resolution
+ * const resolutionResult = await DidWeb.resolve({ did: did.uri });
+ * ```
+ */
+export class DidWeb extends DidMethod {
+
+  /**
+   * Name of the DID method, as defined in the DID Web specification.
+   */
+  public static methodName = 'web';
+
+  /**
+   * Resolves a `did:web` identifier to a DID Document.
+   *
+   * @param didUri - The DID to be resolved.
+   * @param _options - Optional parameters for resolving the DID. Unused by this DID method.
+   * @returns A Promise resolving to a {@link DidResolutionResult} object representing the result of the resolution.
+   */
+  public static async resolve(didUri: string, _options?: DidResolutionOptions): Promise<DidResolutionResult> {
+    // Attempt to parse the DID URI.
+    const parsedDid = Did.parse(didUri);
+
+    // If parsing failed, the DID is invalid.
+    if (!parsedDid) {
+      return {
+        ...EMPTY_DID_RESOLUTION_RESULT,
+        didResolutionMetadata: { error: 'invalidDid' }
+      };
+    }
+
+    // If the DID method is not "web", return an error.
+    if (parsedDid.method !== DidWeb.methodName) {
+      return {
+        ...EMPTY_DID_RESOLUTION_RESULT,
+        didResolutionMetadata: { error: 'methodNotSupported' }
+      };
+    }
+
+    // Replace ":" with "/" in the identifier and prepend "https://" to obtain the fully qualified
+    // domain name and optional path.
+    let baseUrl = `https://${parsedDid.id.replace(/:/g, '/')}`;
+
+    // If the domain contains a percent encoded port value, decode the colon.
+    baseUrl = decodeURIComponent(baseUrl);
+
+    // Append the expected location of the DID document depending on whether a path was specified.
+    const didDocumentUrl = parsedDid.id.includes(':') ?
+      `${baseUrl}/did.json` :
+      `${baseUrl}/.well-known/did.json`;
+
+    try {
+      // Perform an HTTP GET request to obtain the DID document.
+      const response = await fetch(didDocumentUrl);
+
+      // If the response status code is not 200, return an error.
+      if (!response.ok) throw new Error('HTTP error status code returned');
+
+      // Parse the DID document.
+      const didDocument = await response.json() as DidDocument;
+
+      return {
+        ...EMPTY_DID_RESOLUTION_RESULT,
+        didDocument,
+      };
+
+    } catch (error: any) {
+      // If the DID document could not be retrieved, return an error.
+      return {
+        ...EMPTY_DID_RESOLUTION_RESULT,
+        didResolutionMetadata: { error: 'notFound' }
+      };
+    }
+  }
+}

package/src/resolver/resolver-cache-level.ts

@@ -0,0 +1,163 @@
+import type { AbstractLevel } from 'abstract-level';
+
+import ms from 'ms';
+import { Level } from 'level';
+
+import type { DidResolutionResult } from '../types/did-core.js';
+import type { DidResolverCache } from '../types/did-resolution.js';
+
+/**
+ * Configuration parameters for creating a LevelDB-based cache for DID resolution results.
+ *
+ * Allows customization of the underlying database instance, storage location, and cache
+ * time-to-live (TTL) settings.
+ */
+export type DidResolverCacheLevelParams = {
+  /**
+   * Optional. An instance of `AbstractLevel` to use as the database. If not provided, a new
+   * LevelDB instance will be created at the specified `location`.
+   */
+  db?: AbstractLevel<string | Buffer | Uint8Array, string, string>;
+
+  /**
+   * Optional. The file system path or IndexedDB name where the LevelDB store will be created.
+   * Defaults to 'DATA/DID_RESOLVERCACHE' if not specified.
+   */
+  location?: string;
+
+  /**
+   * Optional. The time-to-live for cache entries, expressed as a string (e.g., '1h', '15m').
+   * Determines how long a cache entry should remain valid before being considered expired. Defaults
+   * to '15m' if not specified.
+   */
+  ttl?: string;
+}
+
+/**
+ * Encapsulates a DID resolution result along with its expiration information for caching purposes.
+ *
+ * This type is used internally by the `DidResolverCacheLevel` to store DID resolution results
+ * with an associated time-to-live (TTL) value. The TTL is represented in milliseconds and
+ * determines when the cached entry is considered expired and eligible for removal.
+ */
+type CachedDidResolutionResult = {
+  /**
+   * The expiration time of the cache entry in milliseconds since the Unix epoch.
+   *
+   * This value is used to calculate whether the cached entry is still valid or has expired.
+   */
+  ttlMillis: number;
+
+  /**
+   * The DID resolution result being cached.
+   *
+   * This object contains the resolved DID document and associated metadata.
+   */
+  value: DidResolutionResult;
+}
+
+/**
+ * A Level-based cache implementation for storing and retrieving DID resolution results.
+ *
+ * This cache uses LevelDB for storage, allowing data persistence across process restarts or
+ * browser refreshes. It's suitable for both Node.js and browser environments.
+ *
+ * @remarks
+ * The LevelDB cache keeps data in memory for fast access and also writes to the filesystem in
+ * Node.js or indexedDB in browsers. Time-to-live (TTL) for cache entries is configurable.
+ *
+ * @example
+ * ```
+ * const cache = new DidResolverCacheLevel({ ttl: '15m' });
+ * ```
+ */
+export class DidResolverCacheLevel implements DidResolverCache {
+  /** The underlying LevelDB store used for caching. */
+  protected cache;
+
+  /** The time-to-live for cache entries in milliseconds. */
+  protected ttl: number;
+
+  constructor({
+    db,
+    location = 'DATA/DID_RESOLVERCACHE',
+    ttl = '15m'
+  }: DidResolverCacheLevelParams = {}) {
+    this.cache = db ?? new Level<string, string>(location);
+    this.ttl = ms(ttl);
+  }
+
+  /**
+   * Retrieves a DID resolution result from the cache.
+   *
+   * If the cached item has exceeded its TTL, it's scheduled for deletion and undefined is returned.
+   *
+   * @param did - The DID string used as the key for retrieving the cached result.
+   * @returns The cached DID resolution result or undefined if not found or expired.
+   */
+  async get(did: string): Promise<DidResolutionResult | void> {
+    try {
+      const str = await this.cache.get(did);
+      const cachedDidResolutionResult: CachedDidResolutionResult = JSON.parse(str);
+
+      if (Date.now() >= cachedDidResolutionResult.ttlMillis) {
+        // defer deletion to be called in the next tick of the js event loop
+        this.cache.nextTick(() => this.cache.del(did));
+
+        return;
+      } else {
+        return cachedDidResolutionResult.value;
+      }
+
+    } catch(error: any) {
+      // Don't throw when a key wasn't found.
+      if (error.notFound) {
+        return;
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Stores a DID resolution result in the cache with a TTL.
+   *
+   * @param did - The DID string used as the key for storing the result.
+   * @param value - The DID resolution result to be cached.
+   * @returns A promise that resolves when the operation is complete.
+   */
+  set(did: string, value: DidResolutionResult): Promise<void> {
+    const cachedDidResolutionResult: CachedDidResolutionResult = { ttlMillis: Date.now() + this.ttl, value };
+    const str = JSON.stringify(cachedDidResolutionResult);
+
+    return this.cache.put(did, str);
+  }
+
+  /**
+   * Deletes a DID resolution result from the cache.
+   *
+   * @param did - The DID string used as the key for deletion.
+   * @returns A promise that resolves when the operation is complete.
+   */
+  delete(did: string): Promise<void> {
+    return this.cache.del(did);
+  }
+
+  /**
+   * Clears all entries from the cache.
+   *
+   * @returns A promise that resolves when the operation is complete.
+   */
+  clear(): Promise<void> {
+    return this.cache.clear();
+  }
+
+  /**
+   * Closes the underlying LevelDB store.
+   *
+   * @returns A promise that resolves when the store is closed.
+   */
+  close(): Promise<void> {
+    return this.cache.close();
+  }
+}

package/src/resolver/resolver-cache-noop.ts

@@ -0,0 +1,26 @@
+import type { DidResolutionResult } from '../types/did-core.js';
+import type { DidResolverCache } from '../types/did-resolution.js';
+
+/**
+ * No-op cache that is used as the default cache for did-resolver.
+ *
+ * The motivation behind using a no-op cache as the default stems from the desire to maximize the
+ * potential for this library to be used in as many JS runtimes as possible.
+ */
+export const DidResolverCacheNoop: DidResolverCache = {
+  get: function (_key: string): Promise<DidResolutionResult> {
+    return null as any;
+  },
+  set: function (_key: string, _value: DidResolutionResult): Promise<void> {
+    return null as any;
+  },
+  delete: function (_key: string): Promise<void> {
+    return null as any;
+  },
+  clear: function (): Promise<void> {
+    return null as any;
+  },
+  close: function (): Promise<void> {
+    return null as any;
+  }
+};