diff --git a/packages/dids/src/methods/did-dht.ts b/packages/dids/src/methods/did-dht.ts index 151b68205..ad9c724aa 100644 --- a/packages/dids/src/methods/did-dht.ts +++ b/packages/dids/src/methods/did-dht.ts @@ -14,7 +14,7 @@ import { Convert } from '@web5/common'; import { CryptoApi, computeJwkThumbprint, Ed25519, LocalKeyManager, Secp256k1, Secp256r1 } from '@web5/crypto'; import { AUTHORITATIVE_ANSWER, decode as dnsPacketDecode, encode as dnsPacketEncode } from '@dnsquery/dns-packet'; -import type { Did, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; +import type { BearerDid, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; import type { DidService, DidDocument, @@ -496,7 +496,7 @@ export class DidDht extends DidMethod { * @param params.keyManager - Optionally specify a Key Management System (KMS) used to generate * keys and sign data. * @param params.options - Optional parameters that can be specified when creating a new DID. - * @returns A Promise resolving to a {@link Did} object representing the new DID. + * @returns A Promise resolving to a {@link BearerDid} object representing the new DID. */ public static async create({ keyManager = new LocalKeyManager(), @@ -504,7 +504,7 @@ export class DidDht extends DidMethod { }: { keyManager?: TKms; options?: DidDhtCreateOptions; - } = {}): Promise { + } = {}): Promise { // Before processing the create operation, validate DID-method-specific requirements to prevent // keys from being generated unnecessarily. @@ -538,12 +538,12 @@ export class DidDht extends DidMethod { } /** - * Instantiates a `Did` object for the DID DHT method from a given {@link PortableDid}. + * Instantiates a {@link BearerDid} object for the DID DHT method from a given {@link PortableDid}. * - * This method allows for the creation of a `Did` object using pre-existing key material, + * This method allows for the creation of a `BearerDid` object using pre-existing key material, * encapsulated within the `verificationMethods` array of the `PortableDid`. This is particularly - * useful when the key material is already available and you want to construct a `Did` object - * based on these keys, instead of generating new keys. + * useful when the key material is already available and you want to construct a `BearerDid` + * object based on these keys, instead of generating new keys. * * @remarks * The key material (both public and private keys) should be provided in JWK format. The method @@ -565,7 +565,7 @@ export class DidDht extends DidMethod { * @param params.keyManager - Optionally specify an external Key Management System (KMS) used to * generate keys and sign data. If not given, a new * {@link @web5/crypto#LocalKeyManager} instance will be created and used. - * @returns A Promise resolving to a `Did` object representing the DID formed from the provided keys. + * @returns A Promise resolving to a `BearerDid` object representing the DID formed from the provided keys. * @throws An error if the `verificationMethods` array does not contain any keys, lacks an * Identity Key, or any verification method is missing a public or private key. */ @@ -577,7 +577,7 @@ export class DidDht extends DidMethod { }: { keyManager?: CryptoApi & KeyImporterExporter; options?: DidDhtCreateOptions; - } & PortableDid): Promise { + } & PortableDid): Promise { if (!(verificationMethods && Array.isArray(verificationMethods) && verificationMethods.length > 0)) { throw new Error(`At least one verification method is required but 0 were given`); } @@ -652,7 +652,7 @@ export class DidDht extends DidMethod { * - The method relies on the specified Pkarr relay server to interface with the DHT network. * * @param params - The parameters for the `publish` operation. - * @param params.did - The `Did` object representing the DID to be published. + * @param params.did - The `BearerDid` object representing the DID to be published. * @param params.gatewayUri - Optional. The URI of a server involved in executing DID * method operations. In the context of publishing, the * endpoint is expected to be a Pkarr relay. If not specified, @@ -669,7 +669,7 @@ export class DidDht extends DidMethod { * ``` */ public static async publish({ did, gatewayUri = DEFAULT_PKARR_RELAY }: { - did: Did; + did: BearerDid; gatewayUri?: string; }): Promise { const isPublished = await DidDhtDocument.put({ did, relay: gatewayUri }); @@ -733,9 +733,9 @@ export class DidDht extends DidMethod { } /** - * Instantiates a `Did` object for the DID DHT method using an array of public keys. + * Instantiates a `BearerDid` object for the DID DHT method using an array of public keys. * - * This method is used to create a `Did` object from a set of public keys, typically after + * This method is used to create a `BearerDid` object from a set of public keys, typically after * these keys have been generated or provided. It constructs the DID document, metadata, and * other necessary components for the DID based on the provided public keys and any additional * options specified. @@ -743,12 +743,12 @@ export class DidDht extends DidMethod { * @param params - The parameters for the DID object creation. * @param params.keyManager - The Key Management System to manage keys. * @param params.options - Additional options for DID creation. - * @returns A Promise resolving to a `Did` object. + * @returns A Promise resolving to a `BearerDid` object. */ private static async fromPublicKeys({ keyManager, verificationMethods, options }: { keyManager: CryptoApi; options: DidDhtCreateOptions; - } & PortableDid): Promise { + } & PortableDid): Promise { // Validate that the given verification methods contain an Identity Key. const identityKey = verificationMethods?.find(vm => vm.id?.split('#').pop() === '0')?.publicKeyJwk; if (!identityKey) { @@ -818,7 +818,7 @@ export class DidDht extends DidMethod { } /** - * Generates a set of keys for use in creating a `Did` object for the `did:dht` method. + * Generates a set of keys for use in creating a `BearerDid` object for the `did:dht` method. * * This method is responsible for generating the cryptographic keys necessary for the DID. It * supports generating keys for the specified verification methods. @@ -914,7 +914,7 @@ class DidDhtDocument { * If publishing fails, `false` is returned. */ public static async put({ did, relay }: { - did: Did; + did: BearerDid; relay: string; }): Promise { // Convert the DID document and DID metadata (such as DID types) to a DNS packet. diff --git a/packages/dids/src/methods/did-ion.ts b/packages/dids/src/methods/did-ion.ts index 09881f7c7..93ab82e99 100644 --- a/packages/dids/src/methods/did-ion.ts +++ b/packages/dids/src/methods/did-ion.ts @@ -17,7 +17,7 @@ import type { DidVerificationMethod, } from '../types/did-core.js'; import type { - Did, + BearerDid, DidMetadata, PortableDid, DidCreateOptions, @@ -282,7 +282,7 @@ export class DidIon extends DidMethod { * @param params.keyManager - Optionally specify a Key Management System (KMS) used to generate * keys and sign data. * @param params.options - Optional parameters that can be specified when creating a new DID. - * @returns A Promise resolving to a {@link Did} object representing the new DID. + * @returns A Promise resolving to a {@link BearerDid} object representing the new DID. */ public static async create({ keyManager = new LocalKeyManager(), @@ -290,7 +290,7 @@ export class DidIon extends DidMethod { }: { keyManager?: TKms; options?: DidIonCreateOptions; - } = {}): Promise { + } = {}): Promise { // Before processing the create operation, validate DID-method-specific requirements to prevent // keys from being generated unnecessarily. @@ -369,7 +369,7 @@ export class DidIon extends DidMethod { * - The method relies on the specified Sidetree node to interface with the network. * * @param params - The parameters for the `publish` operation. - * @param params.did - The `Did` object representing the DID to be published. + * @param params.did - The `BearerDid` object representing the DID to be published. * @param params.gatewayUri - Optional. The URI of a server involved in executing DID * method operations. In the context of publishing, the * endpoint is expected to be a Sidetree node. If not @@ -386,7 +386,7 @@ export class DidIon extends DidMethod { * ``` */ public static async publish({ did, gatewayUri = DEFAULT_GATEWAY_URI }: { - did: Did; + did: BearerDid; gatewayUri?: string; }): Promise { // Create the ION document. @@ -512,9 +512,9 @@ export class DidIon extends DidMethod { } /** - * Instantiates a `Did` object for the DID ION method using an array of public keys. + * Instantiates a `BearerDid` object for the DID ION method using an array of public keys. * - * This method is used to create a `Did` object from a set of public keys, typically after + * This method is used to create a `BearerDid` object from a set of public keys, typically after * these keys have been generated or provided. It constructs the DID document, metadata, and * other necessary components for the DID based on the provided public keys and any additional * options specified. @@ -522,12 +522,12 @@ export class DidIon extends DidMethod { * @param params - The parameters for the DID object creation. * @param params.keyManager - The Key Management System to manage keys. * @param params.options - Additional options for DID creation. - * @returns A Promise resolving to a `Did` object. + * @returns A Promise resolving to a `BearerDid` object. */ private static async fromPublicKeys({ keyManager, recoveryKey, updateKey, verificationMethods, options }: { keyManager: CryptoApi; options: DidIonCreateOptions; - } & IonPortableDid): Promise { + } & IonPortableDid): Promise { // Validate an ION Recovery Key was generated or provided. if (!recoveryKey) { throw new Error('Missing required input: ION Recovery Key'); @@ -570,7 +570,7 @@ export class DidIon extends DidMethod { } /** - * Generates a set of keys for use in creating a `Did` object for the DID ION method. + * Generates a set of keys for use in creating a `BearerDid` object for the DID ION method. * * This method is responsible for generating the cryptographic keys necessary for the DID, * including the ION Update and Recovery keys and any verification methods specified in the diff --git a/packages/dids/src/methods/did-jwk.ts b/packages/dids/src/methods/did-jwk.ts index 9294caf28..9652bee73 100644 --- a/packages/dids/src/methods/did-jwk.ts +++ b/packages/dids/src/methods/did-jwk.ts @@ -11,7 +11,7 @@ import type { import { Convert } from '@web5/common'; import { LocalKeyManager } from '@web5/crypto'; -import type { Did, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; +import type { BearerDid, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; import type { DidDocument, DidResolutionOptions, DidResolutionResult, DidVerificationMethod } from '../types/did-core.js'; import { DidUri } from '../did-uri.js'; @@ -167,7 +167,7 @@ export class DidJwk extends DidMethod { * @param params.keyManager - Optionally specify a Key Management System (KMS) used to generate * keys and sign data. * @param params.options - Optional parameters that can be specified when creating a new DID. - * @returns A Promise resolving to a {@link Did} object representing the new DID. + * @returns A Promise resolving to a {@link BearerDid} object representing the new DID. */ public static async create({ keyManager = new LocalKeyManager(), @@ -175,7 +175,7 @@ export class DidJwk extends DidMethod { }: { keyManager?: TKms; options?: DidJwkCreateOptions; - } = {}): Promise { + } = {}): Promise { if (options.algorithm && options.verificationMethods) { throw new Error(`The 'algorithm' and 'verificationMethods' options are mutually exclusive`); } @@ -195,12 +195,13 @@ export class DidJwk extends DidMethod { } /** - * Instantiates a `Did` object for the `did:jwk` method from a given {@link PortableDid}. + * Instantiates a {@link BearerDid} object for the `did:jwk` method from a given + * {@link PortableDid}. * - * This method allows for the creation of a `Did` object using pre-existing key material, + * This method allows for the creation of a `BearerDid` object using pre-existing key material, * encapsulated within the `verificationMethods` array of the `PortableDid`. This is particularly - * useful when the key material is already available and you want to construct a `Did` object - * based on these keys, instead of generating new keys. + * useful when the key material is already available and you want to construct a `BearerDid` + * object based on these keys, instead of generating new keys. * * @remarks * The `verificationMethods` array must contain exactly one key since the `did:jwk` method only @@ -224,7 +225,7 @@ export class DidJwk extends DidMethod { * @param params.keyManager - Optionally specify an external Key Management System (KMS) used to * generate keys and sign data. If not given, a new * {@link @web5/crypto#LocalKeyManager} instance will be created and used. - * @returns A Promise resolving to a `Did` object representing the DID formed from the provided keys. + * @returns A Promise resolving to a `BearerDid` object representing the DID formed from the provided keys. * @throws An error if the `verificationMethods` array does not contain exactly one entry. */ public static async fromKeys({ @@ -233,7 +234,7 @@ export class DidJwk extends DidMethod { }: { keyManager?: CryptoApi & KeyImporterExporter; options?: unknown; - } & PortableDid): Promise { + } & PortableDid): Promise { if (!verificationMethods || verificationMethods.length !== 1) { throw new Error(`Only one verification method can be specified but ${verificationMethods?.length ?? 0} were given`); } @@ -368,18 +369,18 @@ export class DidJwk extends DidMethod { } /** - * Instantiates a `Did` object for the DID JWK method from a given public key. + * Instantiates a {@link BearerDid} object for the DID JWK method from a given public key. * * @param params - The parameters for the operation. * @param params.keyManager - A Key Management System (KMS) instance for managing keys and * performing cryptographic operations. * @param params.publicKey - The public key of the DID in JWK format. - * @returns A Promise resolving to a `Did` object representing the DID formed from the provided public key. + * @returns A Promise resolving to a `BearerDid` object representing the DID formed from the provided public key. */ private static async fromPublicKey({ keyManager, publicKey }: { keyManager: CryptoApi; publicKey: Jwk; - }): Promise { + }): Promise { // Serialize the public key JWK to a UTF-8 string and encode to Base64URL format. const base64UrlEncoded = Convert.object(publicKey).toBase64Url(); diff --git a/packages/dids/src/methods/did-key.ts b/packages/dids/src/methods/did-key.ts index 5a1476192..f986bfe62 100644 --- a/packages/dids/src/methods/did-key.ts +++ b/packages/dids/src/methods/did-key.ts @@ -20,7 +20,7 @@ import { LocalKeyManager, } from '@web5/crypto'; -import type { Did, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; +import type { BearerDid, DidCreateOptions, DidCreateVerificationMethod, DidMetadata, PortableDid } from './did-method.js'; import type { DidDocument, DidResolutionOptions, DidResolutionResult, DidVerificationMethod } from '../types/did-core.js'; import { DidUri } from '../did-uri.js'; @@ -336,7 +336,7 @@ export class DidKey extends DidMethod { * @param params - The parameters for the create operation. * @param params.keyManager - Key Management System (KMS) used to generate keys and sign data. * @param params.options - Optional parameters that can be specified when creating a new DID. - * @returns A Promise resolving to a {@link Did} object representing the new DID. + * @returns A Promise resolving to a {@link BearerDid} object representing the new DID. */ public static async create({ keyManager = new LocalKeyManager(), @@ -344,7 +344,7 @@ export class DidKey extends DidMethod { }: { keyManager?: TKms; options?: DidKeyCreateOptions; - } = {}): Promise { + } = {}): Promise { if (options.algorithm && options.verificationMethods) { throw new Error(`The 'algorithm' and 'verificationMethods' options are mutually exclusive`); } @@ -364,12 +364,13 @@ export class DidKey extends DidMethod { } /** - * Instantiates a `Did` object for the `did:jwk` method from a given {@link PortableDid}. + * Instantiates a {@link BearerDid} object for the `did:jwk` method from a given + * {@link PortableDid}. * - * This method allows for the creation of a `Did` object using pre-existing key material, + * This method allows for the creation of a `BearerDid` object using pre-existing key material, * encapsulated within the `verificationMethods` array of the `PortableDid`. This is particularly - * useful when the key material is already available and you want to construct a `Did` object - * based on these keys, instead of generating new keys. + * useful when the key material is already available and you want to construct a `BearerDid` + * object based on these keys, instead of generating new keys. * * @remarks * The `verificationMethods` array must contain exactly one key since the `did:jwk` method only @@ -393,7 +394,7 @@ export class DidKey extends DidMethod { * @param params.keyManager - Optionally specify an external Key Management System (KMS) used to * generate keys and sign data. If not given, a new * {@link @web5/crypto#LocalKeyManager} instance will be created and used. - * @returns A Promise resolving to a `Did` object representing the DID formed from the provided keys. + * @returns A Promise resolving to a `BearerDid` object representing the DID formed from the provided keys. * @throws An error if the `verificationMethods` array does not contain exactly one entry. */ public static async fromKeys({ @@ -403,7 +404,7 @@ export class DidKey extends DidMethod { }: { keyManager?: CryptoApi & KeyImporterExporter; options?: DidKeyCreateOptions; - } & PortableDid): Promise { + } & PortableDid): Promise { if (!verificationMethods || verificationMethods.length !== 1) { throw new Error(`Only one verification method can be specified but ${verificationMethods?.length ?? 0} were given`); } @@ -972,7 +973,7 @@ export class DidKey extends DidMethod { keyManager: CryptoApi; publicKey: Jwk; options: DidKeyCreateOptions; - }): Promise { + }): Promise { // Convert the public key to a byte array and encode to Base64URL format. const multibaseId = await DidKeyUtils.publicKeyToMultibaseId({ publicKey }); diff --git a/packages/dids/src/methods/did-method.ts b/packages/dids/src/methods/did-method.ts index 7746ded15..54751b548 100644 --- a/packages/dids/src/methods/did-method.ts +++ b/packages/dids/src/methods/did-method.ts @@ -20,9 +20,10 @@ import { DidVerificationRelationship } from '../types/did-core.js'; import { DidError, DidErrorCode } from '../did-error.js'; /** - * Represents a Decentralized Identifier (DID) along with its convenience functions. + * Represents a Decentralized Identifier (DID) along with its DID document, key manager, metadata, + * and convenience functions. */ -export interface Did { +export interface BearerDid { /** * The DID document associated with this DID. */ @@ -124,13 +125,14 @@ export type DidMetadata = { } /** - * Defines the API for a specific DID method. It includes functionalities for creating and resolving DIDs. + * 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< - TDid extends Did, + TDid extends BearerDid, TOptions extends DidCreateOptions, TKms extends CryptoApi | undefined = undefined > extends DidMethodResolver { @@ -208,7 +210,7 @@ export interface DidMethodResolver { * // Export the DID to a PortableDid. * const portableDid = await DidExample.toKeys({ did }); * - * // Instantiate a `Did` object from the PortableDid metadata. + * // Instantiate a BearerDid object from a PortableDid. * const didFromKeys = await DidExample.fromKeys({ ...portableDid }); * // The `didFromKeys` object should be equivalent to the original `did` object. * ``` @@ -286,23 +288,23 @@ export interface PortableDidVerificationMethod extends Partial { + }): Promise { // Resolve the DID URI to a DID document and document metadata. const { didDocument, didDocumentMetadata, didResolutionMetadata } = await this.resolve(didUri); @@ -452,7 +454,7 @@ export class DidMethod { } /** - * Converts a `Did` object to a portable format containing the URI and verification methods + * Converts a `BearerDid` object to a portable format containing the URI and verification methods * associated with the DID. * * This method is useful when you need to represent the key material and metadata associated with @@ -471,18 +473,18 @@ export class DidMethod { * * @example * ```ts - * // Assuming `did` is an instance of Did + * // Assuming `did` is an instance of BearerDid * const portableDid = await DidMethod.toKeys({ did }); * // portableDid now contains the verification methods and their associated keys. * ``` * * @param params - The parameters for the convert operation. - * @param params.did - The `Did` object to convert to a portable format. + * @param params.did - The `BearerDid` object to convert to a portable format. * @returns A `PortableDid` containing the URI and verification methods associated with the DID. * @throws An error if the key manager does not support key export or if the DID document * is missing verification methods. */ - public static async toKeys({ did }: { did: Did }): Promise { + public static async toKeys({ did }: { did: BearerDid }): Promise { // First, confirm that the DID's key manager supports exporting keys. if (!('exportKey' in did.keyManager && typeof did.keyManager.exportKey === 'function')) { throw new Error(`The key manager of the given DID does not support exporting keys`); diff --git a/packages/dids/tests/fixtures/test-vectors/did-ion/to-keys.ts b/packages/dids/tests/fixtures/test-vectors/did-ion/to-keys.ts index ce4c46358..b69eeace1 100644 --- a/packages/dids/tests/fixtures/test-vectors/did-ion/to-keys.ts +++ b/packages/dids/tests/fixtures/test-vectors/did-ion/to-keys.ts @@ -2,11 +2,11 @@ import type { Jwk, LocalKeyManager } from '@web5/crypto'; import sinon from 'sinon'; -import type { Did } from '../../../../src/methods/did-method.js'; +import type { BearerDid } from '../../../../src/methods/did-method.js'; type TestVector = { [key: string]: { - did: Did; + did: BearerDid; privateKey: Jwk[]; }; }; diff --git a/packages/dids/tests/methods/did-method.spec.ts b/packages/dids/tests/methods/did-method.spec.ts index 300af0d29..7cb9daf44 100644 --- a/packages/dids/tests/methods/did-method.spec.ts +++ b/packages/dids/tests/methods/did-method.spec.ts @@ -4,7 +4,7 @@ import sinon from 'sinon'; import { expect } from 'chai'; import { LocalKeyManager } from '@web5/crypto'; -import type { Did } from '../../src/methods/did-method.js'; +import type { BearerDid } from '../../src/methods/did-method.js'; import type { DidDocument, DidVerificationMethod } from '../../src/types/did-core.js'; import { DidMethod } from '../../src/methods/did-method.js'; @@ -175,7 +175,7 @@ describe('DidMethod', () => { }); describe('toKeys()', () => { - let didJwk: Did; + let didJwk: BearerDid; beforeEach(async () => { didJwk = { @@ -289,7 +289,7 @@ describe('DidMethod', () => { }; // Create a DID to use for the test. - const did: Did = { + const did: BearerDid = { didDocument : { id: 'did:jwk:123' }, keyManager : keyManagerWithoutExport, getSigner : sinon.stub(),