@dwn-protocol/id-sdk 0.2.5 → 0.2.6

package/src/dids/did-resolver.ts

@@ -1,107 +0,0 @@
-import type {
-  DidResolverCache,
-  DidMethodResolver,
-  DidResolutionResult,
-  DidResolutionOptions,
-} from './types.js';
-
-import { parseDid } from './utils.js';
-import { DidResolverCacheNoop } from './resolver-cache-noop.js';
-
-export type DidResolverOptions = {
-  didResolvers: DidMethodResolver[];
-  cache?: DidResolverCache;
-}
-
-/**
- * The `DidResolver` class is responsible for resolving DIDs to DID documents.
- * It uses method resolvers to resolve DIDs of different methods and a cache
- * to store resolved DID documents.
- */
-export class DidResolver {
-  /**
-   * A cache for storing resolved DID documents.
-   */
-  private cache: DidResolverCache;
-
-  /**
-   * A map to store method resolvers against method names.
-   */
-  private didResolvers: Map<string, DidMethodResolver> = new Map();
-
-  /**
-   * Constructs a new `DidResolver`.
-   *
-   * @param options - The options for constructing the `DidResolver`.
-   * @param options.didResolvers - An array of `DidMethodResolver` instances.
-   * @param options.cache - Optional. A cache for storing resolved DID documents. If not provided, a no-operation cache is used.
-   */
-  constructor(options: DidResolverOptions) {
-    this.cache = options.cache || DidResolverCacheNoop;
-
-    for (const resolver of options.didResolvers) {
-      this.didResolvers.set(resolver.methodName, resolver);
-    }
-  }
-
-  /**
-   * Resolves a DID to a DID Resolution Result.
-   * If the DID Resolution Result is present in the cache, it returns the cached
-   * result. Otherwise, it uses the appropriate method resolver to resolve
-   * the DID, stores the resolution result in the cache, and returns the
-   * resolultion result.
-   *
-   * Note: The method signature for resolve() in this implementation must match
-   * the `DidResolver` implementation in
-   * {@link https://github.com/@dwn-protocol/id | @dwn-protocol/id} so that
-   * IDDwn apps and the underlying DWN instance can share the same DID
-   * resolution cache.
-   *
-   * @param didUrl - The DID or DID URL to resolve.
-   * @returns A promise that resolves to the DID Resolution Result.
-   */
-  async resolve(didUrl: string, resolutionOptions?: DidResolutionOptions): Promise<DidResolutionResult> {
-
-    const parsedDid = parseDid({ didUrl });
-    if (!parsedDid) {
-      return {
-        '@context'            : 'https://w3id.org/did-resolution/v1',
-        didDocument           : undefined,
-        didDocumentMetadata   : {},
-        didResolutionMetadata : {
-          contentType  : 'application/did+json',
-          error        : 'invalidDid',
-          errorMessage : `Cannot parse DID: ${didUrl}`
-        }
-      };
-    }
-
-    const resolver = this.didResolvers.get(parsedDid.method);
-    if (!resolver) {
-      return {
-        '@context'            : 'https://w3id.org/did-resolution/v1',
-        didDocument           : undefined,
-        didDocumentMetadata   : {},
-        didResolutionMetadata : {
-          contentType  : 'application/did+json',
-          error        : 'methodNotSupported',
-          errorMessage : `Method not supported: ${parsedDid.method}`
-        }
-      };
-    }
-
-    const cachedResolutionResult = await this.cache.get(parsedDid.did);
-
-    if (cachedResolutionResult) {
-      return cachedResolutionResult;
-    } else {
-      const resolutionResult = await resolver.resolve({
-        didUrl: parsedDid.did,
-        resolutionOptions
-      });
-      await this.cache.set(parsedDid.did, resolutionResult);
-
-      return resolutionResult;
-    }
-  }
-}

package/src/dids/index.ts

@@ -1,9 +0,0 @@
-export * from './dht.js';
-export * from './did-dht.js';
-export * from './did-ion.js';
-export * from './did-key.js';
-export * from './did-resolver.js';
-export * from './resolver-cache-level.js';
-export * from './resolver-cache-noop.js';
-export * from './types.js';
-export * as utils from './utils.js';

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

@@ -1,82 +0,0 @@
-import type { DidResolutionResult, DidResolverCache } from './types.js';
-
-import ms from 'ms';
-import { Level } from 'level';
-
-export type DidResolverCacheOptions = {
-  location?: string;
-  ttl?: string;
-}
-
-type CacheWrapper = {
-  ttlMillis: number;
-  value: DidResolutionResult;
-}
-
-/**
- * Naive level-based cache for did resolution results. It just so happens that level aggressively keeps as much as it
- * can in memory when possible while also writing to the filesystem (in node runtime) and indexedDB (in browser runtime).
- * the persistent aspect is especially useful across page refreshes.
- */
-export class DidResolverCacheLevel implements DidResolverCache {
-  private cache: Level<string, string>;
-  private ttl: number;
-
-  private static defaultOptions: Required<DidResolverCacheOptions> = {
-    location : 'data/AGENT/DID_RESOLVERCACHE',
-    ttl      : '15m'
-  };
-
-  constructor(options: DidResolverCacheOptions = {}) {
-    let { location, ttl } = options;
-
-    location ??= DidResolverCacheLevel.defaultOptions.location;
-    ttl ??= DidResolverCacheLevel.defaultOptions.ttl;
-
-    this.cache = new Level(location);
-    this.ttl = ms(ttl);
-  }
-
-  async get(did: string): Promise<DidResolutionResult | void> {
-    try {
-      const str = await this.cache.get(did);
-      const cacheWrapper: CacheWrapper = JSON.parse(str);
-
-      if (Date.now() >= cacheWrapper.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 cacheWrapper.value;
-      }
-
-    } catch(error: any) {
-      // Don't throw when a key wasn't found.
-      if (error.code === 'LEVEL_NOT_FOUND') {
-        return;
-      }
-
-      throw error;
-    }
-  }
-
-  set(did: string, value: DidResolutionResult): Promise<void> {
-    const cacheWrapper: CacheWrapper = { ttlMillis: Date.now() + this.ttl, value };
-    const str = JSON.stringify(cacheWrapper);
-
-    return this.cache.put(did, str);
-  }
-
-  delete(did: string): Promise<void> {
-    return this.cache.del(did);
-  }
-
-  clear(): Promise<void> {
-    return this.cache.clear();
-  }
-
-  close(): Promise<void> {
-    return this.cache.close();
-  }
-}

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

@@ -1,25 +0,0 @@
-import type { DidResolutionResult, DidResolverCache } from './types.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;
-  }
-};

package/src/dids/types.ts

@@ -1,278 +0,0 @@
-import type { KeyValueStore } from '../common/index.js';
-import type { PrivateKeyJwk, PublicKeyJwk } from '../crypto/index.js';
-
-import { DidKeyKeySet } from './did-key.js';
-import { DidIonKeySet } from './did-ion.js';
-import { DidDhtKeySet } from './did-dht.js';
-
-export type DidDocument = {
-  '@context'?: 'https://www.w3.org/ns/did/v1' | string | string[];
-  id: string;
-  alsoKnownAs?: string[];
-  controller?: string | string[];
-  verificationMethod?: VerificationMethod[];
-  service?: DidService[];
-  assertionMethod?: VerificationMethod[] | string[];
-  authentication?: VerificationMethod[] | string[];
-  keyAgreement?: VerificationMethod[] | string[];
-  capabilityDelegation?: VerificationMethod[] | string[];
-  capabilityInvocation?: VerificationMethod[] | string[];
-}
-
-export type DidDocumentMetadata = {
-  // indicates the timestamp of the Create operation. ISO8601 timestamp
-  created?: string
-  // indicates the timestamp of the last Update operation for the document version which was
-  // resolved. ISO8601 timestamp
-  updated?: string
-  // indicates whether the DID has been deactivated
-  deactivated?: boolean
-  // indicates the version of the last Update operation for the document version which
-  // was resolved
-  versionId?: string
-  // indicates the timestamp of the next Update operation if the resolved document version
-  // is not the latest version of the document.
-  nextUpdate?: string
-  // indicates the version of the next Update operation if the resolved document version
-  // is not the latest version of the document.
-  nextVersionId?: string
-  // @see https://www.w3.org/TR/did-core/#dfn-equivalentid
-  equivalentId?: string
-  // @see https://www.w3.org/TR/did-core/#dfn-canonicalid
-  canonicalId?: string
-  // Additional output metadata generated during DID Resolution.
-  [key: string]: any
-};
-
-export type DidKeySet = DidKeyKeySet | DidIonKeySet | DidDhtKeySet;
-
-export type DidKeySetVerificationMethodKey = {
-  /** Unique identifier for the key in the KeyManager store. */
-  keyManagerId?: string;
-  publicKeyJwk?: PublicKeyJwk;
-  privateKeyJwk?: PrivateKeyJwk;
-  relationships: VerificationRelationship[];
-}
-
-export type DidMetadata = {
-  /**
-   * Additional properties of any type.
-   */
-  [key: string]: any;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface DidMethod {}
-
-export interface DidMethodApi extends DidMethodOperator, DidMethodResolver {
-  new (): DidMethod;
-  methodName: string;
-}
-
-export interface DidMethodResolver {
-  new (): DidMethod;
-  methodName: string;
-
-  resolve(options: {
-    didUrl: string,
-    resolutionOptions?: DidResolutionOptions
-  }): Promise<DidResolutionResult>;
-}
-
-export interface DidMethodOperator {
-  new (): DidMethod;
-  methodName: string;
-
-  create(options: any): Promise<PortableDid>;
-
-  generateKeySet(): Promise<DidKeySet>;
-
-  getDefaultSigningKey(options: { didDocument: DidDocument }): Promise<string | undefined>;
-}
-
-/**
- * Services are used in DID documents to express ways of communicating with the DID subject or associated entities.
- * A service can be any type of service the DID subject wants to advertise.
- *
- * @see {@link https://www.w3.org/TR/did-core/#services}
- */
-export type DidService = {
-  id: string;
-  type: string;
-  serviceEndpoint: string | DidServiceEndpoint | DidServiceEndpoint[];
-  description?: string;
-};
-
-/**
- * A service endpoint is a URI (Uniform Resource Identifier) that can be used to interact with the service.
- *
- * @see {@link https://www.w3.org/TR/did-core/#dfn-serviceendpoint}
- */
-export interface DidServiceEndpoint {
-  [key: string]: any;
-}
-
-export interface DwnServiceEndpoint extends DidServiceEndpoint {
-  encryptionKeys?: string[];
-  nodes: string[];
-  signingKeys: string[];
-}
-
-export type DidResolutionMetadata = {
-  contentType?: string
-
-  error?:
-    /**
-     * When an unexpected error occurs during DID Resolution or DID URL dereferencing, the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be internalError.
-     */
-    | 'internalError'
-
-    /**
-     * If an invalid DID is detected during DID Resolution, the value of the
-     * DID Resolution Metadata error property MUST be invalidDid.
-     */
-    | 'invalidDid'
-
-    /**
-     * If a DID method is not supported during DID Resolution or DID URL
-     * dereferencing, the value of the DID Resolution or DID URL Dereferencing
-     * Metadata error property MUST be methodNotSupported.
-     */
-    | 'methodNotSupported'
-
-    /**
-     * If during DID Resolution or DID URL dereferencing a DID or DID URL
-     * doesn't exist, the value of the DID Resolution or DID URL dereferencing
-     * Metadata error property MUST be notFound.
-     */
-    | 'notFound'
-
-    /**
-     * If a DID document representation is not supported during DID Resolution
-     * or DID URL dereferencing, the value of the DID Resolution Metadata error
-     * property MUST be representationNotSupported.
-     */
-    | 'representationNotSupported'
-    | string
-
-  // Additional output metadata generated during DID Resolution.
-  [key: string]: any
-};
-
-/**
- * DID Resolution input metadata.
- *
- * @see {@link https://www.w3.org/TR/did-core/#did-resolution-options}
- */
-export interface DidResolutionOptions {
-  accept?: string
-
-  // Additional properties used during DID Resolution.
-  [key: string]: any
-}
-
-export type DidResolutionResult = {
-  '@context'?: 'https://w3id.org/did-resolution/v1' | string | string[]
-  didResolutionMetadata: DidResolutionMetadata
-  didDocument?: DidDocument
-  didDocumentMetadata: DidDocumentMetadata
-};
-
-/**
- * implement this interface to provide your own cache for did resolution results. can be plugged in through IDDwn API
- */
-export type DidResolverCache = KeyValueStore<string, DidResolutionResult | void>;
-
-/**
- * Format to document a DID identifier, along with its associated data,
- * which can be exported, saved to a file, or imported. The intent is
- * bundle all of the necessary metadata to enable usage of the DID in
- * different contexts.
- */
-export interface PortableDid {
-  did: string;
-
-  /**
-   * A DID method can define different forms of a DID that are logically
-   * equivalent. An example is when a DID takes one form prior to registration
-   * in a verifiable data registry and another form after such registration.
-   * This is the purpose of the canonicalId property.
-   *
-   * The `canonicalId` must be used as the primary ID for the DID subject,
-   * with all other equivalent values treated as secondary aliases.
-   *
-   * @see {@link https://www.w3.org/TR/did-core/#dfn-canonicalid | W3C DID Document Metadata}
-   */
-  canonicalId?: string;
-
-  /**
-   * A set of data describing the DID subject, including mechanisms, such as
-   * cryptographic public keys, that the DID subject or a DID delegate can use
-   * to authenticate itself and prove its association with the DID.
-   */
-  document: DidDocument;
-
-  /**
-   * A collection of cryptographic keys associated with the DID subject. The
-   * `keySet` encompasses various forms, such as recovery keys, update keys,
-   * and verification method keys, to enable authentication and verification
-   * of the DID subject's association with the DID.
-   */
-  keySet: DidKeySet;
-
-  /**
-   * This property can be used to store method specific data about
-   * each managed DID and additional properties of any type.
-   */
-  metadata?: DidMetadata;
-}
-
-export type VerificationMethod = {
-  id: string;
-  // one of the valid verification method types as per
-  // https://www.w3.org/TR/did-spec-registries/#verification-method-types
-  type: string;
-  // DID of the key's controller
-  controller: string;
-  // a JSON Web Key that conforms to https://datatracker.ietf.org/doc/html/rfc7517
-  publicKeyJwk?: PublicKeyJwk;
-  // an encoded (e.g, base58) key with a Multibase-prefix that conforms to
-  // https://datatracker.ietf.org/doc/draft-multiformats-multibase/
-  publicKeyMultibase?: string;
-};
-
-export type VerificationRelationship =
-  /**
-   * Used to specify how the DID subject is expected to express claims, such
-   * as for the purposes of issuing a Verifiable Credential
-   */
-  | 'assertionMethod'
-
-  /**
-   * Used to specify how the DID subject is expected to be authenticated, for
-   * purposes such as logging into a website or engaging in any sort of
-   * challenge-response protocol.
-   */
-  | 'authentication'
-
-  /**
-   * Used to specify how an entity can generate encryption material in order to
-   * transmit confidential information intended for the DID subject, such as
-   * for the purposes of establishing a secure communication channel with the
-   * recipient.
-   */
-  | 'keyAgreement'
-
-  /**
-   * Used to specify a mechanism that might be used by the DID subject to
-   * delegate a cryptographic capability to another party, such as delegating
-   * the authority to access a specific HTTP API to a subordinate.
-   */
-  | 'capabilityDelegation'
-
-  /**
-   * Used to specify a verification method that might be used by the DID
-   * subject to invoke a cryptographic capability, such as the authorization
-   * to update the DID Document.
-   */
-  | 'capabilityInvocation';

package/src/dids/utils.ts

@@ -1,129 +0,0 @@
-import type { PublicKeyJwk } from '../crypto/index.js';
-import { parse, type ParsedDID } from 'did-resolver';
-
-import type { DidDocument, DidService, DidServiceEndpoint, DwnServiceEndpoint } from './types.js';
-
-export interface ParsedDid {
-  did: string
-  didUrl: string
-  method: string
-  id: string
-  path?: string
-  fragment?: string
-  query?: string
-  params?: ParsedDID['params']
-}
-
-export const DID_REGEX = /^did:([a-z0-9]+):((?:(?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))*:)*((?:[a-zA-Z0-9._-]|(?:%[0-9a-fA-F]{2}))+))((;[a-zA-Z0-9_.:%-]+=[a-zA-Z0-9_.:%-]*)*)(\/[^#?]*)?([?][^#]*)?(#.*)?$/;
-
-/**
- * Retrieves services from a given DID document based on provided options.
- * If no `id` or `type` filters are provided, all defined services are returned.
- *
- * Note: The DID document must adhere to the W3C DID specification.
- *
- * @param options - An object containing input parameters for retrieving services.
- * @param options.didDocument - The DID document from which services are retrieved.
- * @param options.id - Optional. A string representing the specific service ID to match. If provided, only the service with this ID will be returned.
- * @param options.type - Optional. A string representing the specific service type to match. If provided, only the service(s) of this type will be returned.
- *
- * @returns An array of services. If no matching service is found, an empty array is returned.
- *
- * @example
- *
- * const didDoc = { ... }; // W3C DID document
- * const services = getServices({ didDocument: didDoc, type: 'DecentralizedWebNode' });
- */
-export function getServices(options: {
-  didDocument: DidDocument,
-  id?: string,
-  type?: string
-}): DidService[] {
-  const { didDocument, id, type } = options ?? {};
-
-  return didDocument?.service?.filter(service => {
-    if (id) {
-      const serviceId = service.id ?? '';
-      const matchesExact = serviceId === id;
-      const matchesFragment = id.startsWith('#') && serviceId.endsWith(id);
-      if (!matchesExact && !matchesFragment) return false;
-    }
-    if (type && service.type !== type) return false;
-    return true;
-  }) ?? [ ];
-}
-
-export function getVerificationMethodIds(options: {
-  didDocument: DidDocument,
-  publicKeyJwk?: PublicKeyJwk,
-  publicKeyMultibase?: string
-}): string | undefined {
-  const { didDocument, publicKeyJwk, publicKeyMultibase } = options;
-  if (!didDocument) throw new Error(`Required parameter missing: 'didDocument'`);
-  if (!didDocument.verificationMethod) throw new Error('Given `didDocument` is missing `verificationMethod` entries.');
-
-  for (let method of didDocument.verificationMethod) {
-    if (publicKeyMultibase && 'publicKeyMultibase' in method) {
-      if (publicKeyMultibase === method.publicKeyMultibase) {
-        return method.id;
-      }
-    } else if (publicKeyJwk && 'crv' in publicKeyJwk &&
-               'publicKeyJwk' in method && 'crv' in method.publicKeyJwk) {
-      if (publicKeyJwk.crv === method.publicKeyJwk.crv &&
-            publicKeyJwk.x === method.publicKeyJwk.x) {
-        return method.id;
-      }
-    }
-  }
-}
-
-/**
- * Retrieves DID verification method types from a given DID document.
- *
- * Note: The DID document must adhere to the W3C DID specification.
- *
- * @param options - An object containing input parameters for retrieving types.
- * @param options.didDocument - The DID document from which types are retrieved.
- *
- * @returns An array of types. If no types were found, an empty array is returned.
- */
-export function getVerificationMethodTypes(options: {
-  didDocument: Record<string, any>
-}): string[] {
-  const { didDocument } = options;
-
-  let types: string[] = [];
-
-  for (let key in didDocument) {
-    if (typeof didDocument[key] === 'object') {
-      types = types.concat(getVerificationMethodTypes({
-        didDocument: didDocument[key]
-      }));
-
-    } else if (key === 'type') {
-      types.push(didDocument[key]);
-    }
-  }
-
-  return [...new Set(types)]; // return only unique types
-}
-
-/**
- * Type guard function to check if the given endpoint is a DwnServiceEndpoint.
- *
- * @param key The endpoint to check.
- * @returns True if the endpoint is a DwnServiceEndpoint, false otherwise.
- */
-export function isDwnServiceEndpoint(endpoint: string | DidServiceEndpoint | DidServiceEndpoint[]): endpoint is DwnServiceEndpoint {
-  return endpoint !== undefined &&
-    typeof endpoint !== 'string' &&
-    !Array.isArray(endpoint) &&
-    'nodes' in endpoint &&
-    'signingKeys' in endpoint;
-}
-
-export function parseDid({ didUrl }: { didUrl: string }): ParsedDid | undefined {
-  const parsedDid: ParsedDid = parse(didUrl);
-
-  return parsedDid;
-}