diff --git a/docs/api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md b/docs/api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md index 8ca9faa8..ee8514bf 100644 --- a/docs/api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md +++ b/docs/api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md @@ -2,6 +2,16 @@ [modules/verifiable-credentials](../modules/modules_verifiable_credentials.md).VerifiableCredentialsServiceBase +Service responsible for managing verifiable credentials and presentations. +You can read more about verifiable credentials data model [here](https://www.w3.org/TR/vc-data-model/). + +```typescript +const { connectToCacheServer } = await initWithPrivateKeySigner(privateKey, rpcUrl); +const { connectToDidRegistry } = await connectToCacheServer(); +const { verifiableCredentialsService } = await connectToDidRegistry(); +verifiableCredentialsService.createRoleVC(...); +``` + ## Table of contents ### Constructors @@ -36,68 +46,103 @@ ▸ **createPresentation**(`verifiableCredential`, `options?`): `Presentation` +Create a presentation with given verifiable credentials. Allow create presentation for a given presentation definition. + +```typescript +verifiableCredentialsService.createPresentation([...credentials]); +``` + #### Parameters -| Name | Type | -| :------ | :------ | -| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | -| `options?` | [`CreatePresentationParams`](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md) | +| Name | Type | Description | +| :------ | :------ | :------ | +| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | role credential parameters | +| `options?` | [`CreatePresentationParams`](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md) | presentation options | #### Returns `Presentation` +presentation + ___ ### createRoleVC ▸ **createRoleVC**(`credentialParams`, `proofOptions?`): `Promise`<`VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>\> +Create a Energy Web role verifiable credential with EIP712 signature. + +```typescript +verifiableCredentialsService.createRoleVC({ + id: 'did:ethr:volta:0x00...0', + namespace: 'root.roles.energyweb.iam.ewc', + version: '1', +}); +``` + #### Parameters -| Name | Type | -| :------ | :------ | -| `credentialParams` | [`RoleCredentialSubjectParams`](../interfaces/modules_verifiable_credentials.RoleCredentialSubjectParams.md) | -| `proofOptions?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | +| Name | Type | Description | +| :------ | :------ | :------ | +| `credentialParams` | [`RoleCredentialSubjectParams`](../interfaces/modules_verifiable_credentials.RoleCredentialSubjectParams.md) | role credential parameters | +| `proofOptions?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options | #### Returns `Promise`<`VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>\> +verifiable credential object + ___ ### createVerifiablePresentation ▸ **createVerifiablePresentation**(`verifiableCredential`, `options?`): `Promise`<`VerifiablePresentation`\> +Create a verifiable presentation with given verifiable credentials and EIP712 signature. + +```typescript +verifiableCredentialsService.createVerifiablePresentation([...credentials]); +``` + #### Parameters -| Name | Type | -| :------ | :------ | -| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | -| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | +| Name | Type | Description | +| :------ | :------ | :------ | +| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | role credential parameters | +| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options | #### Returns `Promise`<`VerifiablePresentation`\> +verifiable presentation + ___ ### initiateExchange -▸ **initiateExchange**(`__namedParameters`): `Promise`<`any`[]\> +▸ **initiateExchange**(`options`): `Promise`<[`InitiateExchangeResults`](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md)[]\> + +Initialize credential exchange. Only vc-api exchanges currently supported. -**`description`** The type of the exchange. Only vc-api exchanges currently supported. +```typescript +verifiableCredentialsService.initiateExchange({ + type: VC_API_EXCHANGE, + url: 'http://localhost:3000', +}); +``` #### Parameters -| Name | Type | -| :------ | :------ | -| `__namedParameters` | `ExchangeInvitation` | +| Name | Type | Description | +| :------ | :------ | :------ | +| `options` | `ExchangeInvitation` | object with options | #### Returns -`Promise`<`any`[]\> +`Promise`<[`InitiateExchangeResults`](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md)[]\> credentials query with matching verifiable presentations @@ -105,7 +150,14 @@ ___ ### verify -▸ **verify**<`T`\>(`vp`, `options?`): `any` +▸ **verify**<`T`\>(`vp`, `options?`): `Promise`<`boolean`\> + +Verify a given credential or presentation. Throws an error if the credential or presentation proof is not valid. + +```typescript +await verifiableCredentialsService.verify(credential); +await verifiableCredentialsService.verify(presentation); +``` #### Type parameters @@ -115,14 +167,16 @@ ___ #### Parameters -| Name | Type | -| :------ | :------ | -| `vp` | `VerifiablePresentation` \| `VerifiableCredential`<`T`\> | -| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | +| Name | Type | Description | +| :------ | :------ | :------ | +| `vp` | `VerifiablePresentation` \| `VerifiableCredential`<`T`\> | verifiable presentation or credential | +| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options | #### Returns -`any` +`Promise`<`boolean`\> + +true if the proof is valid ___ diff --git a/docs/api/interfaces/modules_verifiable_credentials.InitiateExchangeResults.md b/docs/api/interfaces/modules_verifiable_credentials.InitiateExchangeResults.md new file mode 100644 index 00000000..18ef21a3 --- /dev/null +++ b/docs/api/interfaces/modules_verifiable_credentials.InitiateExchangeResults.md @@ -0,0 +1,22 @@ +# Interface: InitiateExchangeResults + +[modules/verifiable-credentials](../modules/modules_verifiable_credentials.md).InitiateExchangeResults + +## Table of contents + +### Properties + +- [presentationDefinition](modules_verifiable_credentials.InitiateExchangeResults.md#presentationdefinition) +- [selectResults](modules_verifiable_credentials.InitiateExchangeResults.md#selectresults) + +## Properties + +### presentationDefinition + +• **presentationDefinition**: `PresentationDefinition` + +___ + +### selectResults + +• **selectResults**: `SelectResults` diff --git a/docs/api/modules/modules_verifiable_credentials.md b/docs/api/modules/modules_verifiable_credentials.md index 654ce26e..7c7b11d4 100644 --- a/docs/api/modules/modules_verifiable_credentials.md +++ b/docs/api/modules/modules_verifiable_credentials.md @@ -9,6 +9,7 @@ ### Interfaces - [CreatePresentationParams](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md) +- [InitiateExchangeResults](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md) - [IssuerFields](../interfaces/modules_verifiable_credentials.IssuerFields.md) - [ProofOptions](../interfaces/modules_verifiable_credentials.ProofOptions.md) - [RoleCredentialSubject](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md) diff --git a/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts b/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts index 7228f75e..0ccd0005 100644 --- a/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts +++ b/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts @@ -1,4 +1,5 @@ -import { IPresentationDefinition } from '@sphereon/pex'; +import { PresentationDefinition } from '@ew-did-registry/credentials-interface'; +import { IPresentationDefinition, SelectResults } from '@sphereon/pex'; import { IssuerFields } from './role-credential.types'; /* @@ -7,20 +8,31 @@ import { IssuerFields } from './role-credential.types'; */ export interface RoleCredentialSubjectParams { /* + * DID of the subject * https://www.w3.org/TR/vc-data-model/#identifiers */ id: string; + + /* Role namespace */ namespace: string; + + /* Role version */ version: string; + + /* Role issuer fields */ issuerFields?: IssuerFields[]; } export interface ProofOptions { + /* Proof verification method */ verificationMethod?: string; + + /* Proof purpose */ proofPurpose?: string; } export interface CreatePresentationParams { + /* Presentation definition from which pick the credentials */ presentationDefinition?: IPresentationDefinition; } @@ -29,3 +41,8 @@ export interface VerifyVerifiableCredentialResults { warnings: string[]; errors: string[]; } + +export interface InitiateExchangeResults { + presentationDefinition: PresentationDefinition; + selectResults: SelectResults; +} diff --git a/src/modules/verifiable-credentials/verifiable-credentials-base.service.ts b/src/modules/verifiable-credentials/verifiable-credentials-base.service.ts index 5d58e8f1..c3b253d0 100644 --- a/src/modules/verifiable-credentials/verifiable-credentials-base.service.ts +++ b/src/modules/verifiable-credentials/verifiable-credentials-base.service.ts @@ -21,16 +21,29 @@ import { verifiableCredentialEIP712Types, verifiablePresentationEIP712Types, verifiablePresentationWithCredentialEIP712Types, + InitiateExchangeResults, } from './types'; import VCStorageClient from './storage-client'; +/** + * Service responsible for managing verifiable credentials and presentations. + * You can read more about verifiable credentials data model [here](https://www.w3.org/TR/vc-data-model/). + * + * ```typescript + * const { connectToCacheServer } = await initWithPrivateKeySigner(privateKey, rpcUrl); + * const { connectToDidRegistry } = await connectToCacheServer(); + * const { verifiableCredentialsService } = await connectToDidRegistry(); + * verifiableCredentialsService.createRoleVC(...); + * ``` + * */ export abstract class VerifiableCredentialsServiceBase { /** - * @param {string} credential - The credential object in JSON format - * @param {string} linked_data_proof_options - The proof options in JSON format - * @param {string} public_key - Information about public key that credential will be signed in JSON format - * @description get prepared data for signing a credential - * @returns {Promise} JSON stringified prepared data (including EIP712 types and credential with proof ready for signing) + * Get prepared data for signing a credential. + * + * @param {String} credential - The credential object in JSON format + * @param {String} linked_data_proof_options - The proof options in JSON format + * @param {String} public_key - Information about public key that credential will be signed in JSON format + * @returns {Promise} JSON stringified prepared data (including EIP712 types and credential with proof ready for signing) */ protected abstract prepareIssueCredential( credential: string, @@ -39,11 +52,12 @@ export abstract class VerifiableCredentialsServiceBase { ): Promise; /** - * @param {string} credential - The credential object in JSON format - * @param {string} preparation - Output of `prepareIssueCredential` method - * @param {string} signature - Signature of the credential - * @description get verifiable credential object - * @returns {Promise} verifiable credential object in JSON format + * Get verifiable credential object. + * + * @param {String} credential - The credential object in JSON format + * @param {String} preparation - Output of `prepareIssueCredential` method + * @param {String} signature - Signature of the credential + * @returns {Promise} verifiable credential object in JSON format */ protected abstract completeIssueCredential( credential: string, @@ -52,10 +66,11 @@ export abstract class VerifiableCredentialsServiceBase { ): Promise; /** - * @param {string} vc - The verifiable credential object in JSON format - * @param {string} proof_options - The proof options in JSON format - * @description verify given verifiable credential - * @returns {Promise} object with results of verification in JSON format + * Verify given verifiable credential. + * + * @param {String} vc - The verifiable credential object in JSON format + * @param {String} proof_options - The proof options in JSON format + * @returns {Promise} object with results of verification in JSON format */ protected abstract verifyCredential( vc: string, @@ -63,11 +78,12 @@ export abstract class VerifiableCredentialsServiceBase { ): Promise; /** - * @param {string} presentation - The presentation object in JSON format - * @param {string} linked_data_proof_options - The proof options in JSON format - * @param {string} public_key - Information about public key that presentation will be signed in JSON format - * @description get prepared data for signing a presentation - * @returns {Promise} JSON stringified prepared data (including EIP712 types and presentation with proof ready for signing) + * Get prepared data for signing a presentation. + * + * @param {String} presentation - The presentation object in JSON format + * @param {String} linked_data_proof_options - The proof options in JSON format + * @param {String} public_key - Information about public key that presentation will be signed in JSON format + * @returns {Promise} JSON stringified prepared data (including EIP712 types and presentation with proof ready for signing) */ protected abstract prepareIssuePresentation( presentation: string, @@ -76,11 +92,12 @@ export abstract class VerifiableCredentialsServiceBase { ): Promise; /** - * @param {string} presentation - The presentation object in JSON format - * @param {string} preparation - Output of `prepareIssuePresentation` method - * @param {string} signature - Signature of the presentation - * @description get verifiable presentation object - * @returns {Promise} verifiable presentation object in JSON format + * Get verifiable presentation object. + * + * @param {String} presentation - The presentation object in JSON format + * @param {String} preparation - Output of `prepareIssuePresentation` method + * @param {String} signature - Signature of the presentation + * @returns {Promise} verifiable presentation object in JSON format */ protected abstract completeIssuePresentation( presentation: string, @@ -89,10 +106,11 @@ export abstract class VerifiableCredentialsServiceBase { ): Promise; /** - * @param {string} vp - The verifiable presentation object in JSON format - * @param {string} proof_options - The proof options in JSON format - * @description verify given verifiable presentation (included verifiable credentials are not verified) - * @returns {Promise} object with results of verification in JSON format + * Verify given verifiable presentation (included verifiable credentials are not verified). + * + * @param {String} vp - The verifiable presentation object in JSON format + * @param {String} proof_options - The proof options in JSON format + * @returns {Promise} object with results of verification in JSON format */ protected abstract verifyPresentation( vp: string, @@ -104,11 +122,32 @@ export abstract class VerifiableCredentialsServiceBase { private readonly _storage: VCStorageClient ) {} + // * Should be overridden by the implementation + static async create( + // eslint-disable-next-line @typescript-eslint/no-unused-vars + signerService: SignerService, + // eslint-disable-next-line @typescript-eslint/no-unused-vars + storage: VCStorageClient + ): Promise { + throw new Error('Not implemented'); + } + /** - * @description The type of the exchange. Only vc-api exchanges currently supported. + * Initialize credential exchange. Only vc-api exchanges currently supported. + * + * ```typescript + * verifiableCredentialsService.initiateExchange({ + * type: VC_API_EXCHANGE, + * url: 'http://localhost:3000', + * }); + * ``` + * @param {ExchangeInvitation} options object with options * @returns credentials query with matching verifiable presentations */ - async initiateExchange({ type, url }: ExchangeInvitation) { + async initiateExchange({ + type, + url, + }: ExchangeInvitation): Promise { if (type !== VC_API_EXCHANGE) { throw new Error('Only VC-API exchange is supported'); } @@ -132,45 +171,20 @@ export abstract class VerifiableCredentialsServiceBase { ); } - // * Should be overridden by the implementation - static async create( - // eslint-disable-next-line @typescript-eslint/no-unused-vars - signerService: SignerService, - // eslint-disable-next-line @typescript-eslint/no-unused-vars - storage: VCStorageClient - ): Promise { - throw new Error('Not implemented'); - } - - // TODO: Host EWF VC Context and Vocab - private createCredential( - params: RoleCredentialSubjectParams - ): Credential { - const credential = { - '@context': ['https://www.w3.org/2018/credentials/v1'], - id: 'urn:uuid:' + uuid(), - type: ['VerifiableCredential', 'EWFRole'], - issuer: this._signerService.didHex, - issuanceDate: new Date().toISOString(), - credentialSubject: { - role: { - namespace: params.namespace, - version: params.version, - }, - issuerFields: params.issuerFields - ? [ - ...params.issuerFields.map((field) => ({ - ...field, - value: field.value.toString(), - })), - ] - : [], - id: params.id, - }, - }; - return credential; - } - + /** + * Create a Energy Web role verifiable credential with EIP712 signature. + * + * ```typescript + * verifiableCredentialsService.createRoleVC({ + * id: 'did:ethr:volta:0x00...0', + * namespace: 'root.roles.energyweb.iam.ewc', + * version: '1', + * }); + * ``` + * @param {RoleCredentialSubjectParams} credentialParams role credential parameters + * @param {ProofOptions} proofOptions proof options + * @returns verifiable credential object + */ public async createRoleVC( credentialParams: RoleCredentialSubjectParams, proofOptions?: ProofOptions @@ -232,6 +246,16 @@ export abstract class VerifiableCredentialsServiceBase { ) as VerifiableCredential; } + /** + * Create a presentation with given verifiable credentials. Allow create presentation for a given presentation definition. + * + * ```typescript + * verifiableCredentialsService.createPresentation([...credentials]); + * ``` + * @param {VerifiableCredential[]} verifiableCredential role credential parameters + * @param {CreatePresentationParams} options presentation options + * @returns presentation + */ public createPresentation( verifiableCredential: VerifiableCredential[], options?: CreatePresentationParams @@ -259,6 +283,16 @@ export abstract class VerifiableCredentialsServiceBase { }; } + /** + * Create a verifiable presentation with given verifiable credentials and EIP712 signature. + * + * ```typescript + * verifiableCredentialsService.createVerifiablePresentation([...credentials]); + * ``` + * @param {VerifiableCredential[]} verifiableCredential role credential parameters + * @param {ProofOptions} options proof options + * @returns verifiable presentation + */ public async createVerifiablePresentation( verifiableCredential: VerifiableCredential[], options?: ProofOptions @@ -301,10 +335,21 @@ export abstract class VerifiableCredentialsServiceBase { }; } + /** + * Verify a given credential or presentation. Throws an error if the credential or presentation proof is not valid. + * + * ```typescript + * await verifiableCredentialsService.verify(credential); + * await verifiableCredentialsService.verify(presentation); + * ``` + * @param {VerifiablePresentation | VerifiableCredential} vp verifiable presentation or credential + * @param {ProofOptions} options proof options + * @returns true if the proof is valid + */ public async verify( vp: VerifiablePresentation | VerifiableCredential, options?: ProofOptions - ) { + ): Promise { let verifyFunc: (vp: string, proof_options: string) => Promise; switch (vp.type.includes('VerifiablePresentation')) { case true: @@ -351,4 +396,39 @@ export abstract class VerifiableCredentialsServiceBase { return true; } + + /** + * Create a credential with given parameters. + * + * @param {RoleCredentialSubjectParams} params verifiable presentation or credential + * @returns Energy Web credential + */ + private createCredential( + params: RoleCredentialSubjectParams + ): Credential { + const credential = { + // TODO: Host EWF VC Context and Vocabulary + '@context': ['https://www.w3.org/2018/credentials/v1'], + id: 'urn:uuid:' + uuid(), + type: ['VerifiableCredential', 'EWFRole'], + issuer: this._signerService.didHex, + issuanceDate: new Date().toISOString(), + credentialSubject: { + role: { + namespace: params.namespace, + version: params.version, + }, + issuerFields: params.issuerFields + ? [ + ...params.issuerFields.map((field) => ({ + ...field, + value: field.value.toString(), + })), + ] + : [], + id: params.id, + }, + }; + return credential; + } }