From 17b5f063f2f5931fe2e9e0f33c517c7a5b0ee96e Mon Sep 17 00:00:00 2001 From: nitro-neal <5314059+nitro-neal@users.noreply.github.com> Date: Wed, 13 Dec 2023 14:05:38 -0600 Subject: [PATCH] Update `@web5/credentials` README (#349) * update readme * updates * Update packages/credentials/README.md Co-authored-by: Frank Hinek * Update packages/credentials/README.md Co-authored-by: Frank Hinek * Update packages/credentials/README.md Co-authored-by: Frank Hinek * Update packages/credentials/README.md Co-authored-by: Frank Hinek * Update packages/credentials/README.md Co-authored-by: Frank Hinek * Update packages/credentials/tests/presentation-exchange.spec.ts Co-authored-by: Frank Hinek * Update packages/credentials/tests/presentation-exchange.spec.ts Co-authored-by: Frank Hinek * minor readme updates --------- Co-authored-by: Frank Hinek Co-authored-by: Moe Jangda --- packages/credentials/README.md | 84 +++++++++++++------ .../credentials/src/presentation-exchange.ts | 4 +- .../credentials/src/verifiable-credential.ts | 4 +- .../tests/presentation-exchange.spec.ts | 7 +- 4 files changed, 67 insertions(+), 32 deletions(-) diff --git a/packages/credentials/README.md b/packages/credentials/README.md index e597abc3a..eae8bb03f 100644 --- a/packages/credentials/README.md +++ b/packages/credentials/README.md @@ -1,17 +1,40 @@ -# Credentials +# `@web5/credentials` -The Credentials package enables the creation, signing, verification, and general processing of `Verifiable Credentials` (VCs). It also has full `Presentation Exchange` support. +The `@web5/credentials` package provides the following functionality: +* creation, signing, verification, and general processing of [Verifiable Credentials (VCs)](https://www.google.com/search?q=w3c+verifiable+credentials&rlz=1C5GCEM_enPK1033PK1033&oq=w3c+verifiable+credentials&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIGCAEQRRg7MgYIAhBFGDvSAQgzMTIwajBqN6gCALACAA&sourceid=chrome&ie=UTF-8). +* [Presentation Exchange](https://identity.foundation/presentation-exchange/) evaluation -## Verifiable Credential +# Table of Contents -### Features +- [`VerifiableCredential`](#verifiablecredential) + - [Features](#features) + - [Usage](#usage) + - [Creating a Verifiable Credential](#creating-a-verifiable-credential) + - [Signing a Verifiable Credential](#signing-a-verifiable-credential) + - [Verifying a Verifiable Credential](#verifying-a-verifiable-credential) + - [Parsing a JWT into a Verifiable Credential](#parsing-a-jwt-into-a-verifiable-credential) + - [`PresentationExchange`](#presentationexchange) + - [Features](#features-1) + - [Usage](#usage-1) + - [Selecting Credentials](#selecting-credentials) + - [Satisfying a Presentation Definition](#satisfying-a-presentation-definition) + - [Create Presentation From Credentials](#create-presentation-from-credentials) + - [Validate Definition](#validate-definition) + - [Validate Submission](#validate-submission) + - [Validate Presentation](#validate-presentation) + + +# `VerifiableCredential` -- Create Verifiable Credentials with flexible data types. -- Sign credentials using decentralized identifiers (DIDs). -- Verify the integrity and authenticity of VCs encoded as JSON Web Tokens (JWTs). -- Parse JWT representations of VCs into `VerifiableCredential` instances. +## Features + +* Create Verifiable Credentials with flexible data types. +* Sign credentials using decentralized identifiers (DIDs). +* Verify the integrity and authenticity of VCs encoded as JSON Web Tokens (JWTs). +* Parse JWT representations of VCs into VerifiableCredential instances. + +## Usage -### Usage: ### Creating a Verifiable Credential Create a new `VerifiableCredential` with the following parameters: @@ -30,7 +53,7 @@ class StreetCredibility { } } -const vc = new VerifiableCredential({ +const vc = await VerifiableCredential.create({ type: "StreetCred", issuer: "did:example:issuer", subject: "did:example:subject", @@ -44,6 +67,7 @@ Sign a `VerifiableCredential` with a DID: - `did`: The did that is signing the VC First create a `Did` object as follows: + ```javascript import { DidKeyMethod } from '@web5/dids'; const issuer = await DidKeyMethod.create(); @@ -51,16 +75,17 @@ const issuer = await DidKeyMethod.create(); Then sign the VC using the `did` object ```javascript -const vcJwt = vc.sign({ did: issuer }); +const vcJwt = await vc.sign({ did: issuer }); ``` ### Verifying a Verifiable Credential -Verify the integrity and authenticity of a VC JWT +Verify the integrity and authenticity of a Verifiable Credential - `vcJwt`: The VC in JWT format as a String. + ```javascript try { - await VerifiableCredential.verify(vcJwt) + await VerifiableCredential.verify({ vcJwt: signedVcJwt }) console.log("VC Verification successful!") } catch (e: Error) { console.log("VC Verification failed: ${e.message}") @@ -73,10 +98,10 @@ Parse a JWT into a `VerifiableCredential` instance `vcJwt`: The VC JWT as a String. ```javascript -const vc = VerifiableCredential.parseJwt(vcJwt) +const vc = VerifiableCredential.parseJwt({ vcJwt: signedVcJwt }) ``` -## Presentation Exchange +## `PresentationExchange` `PresentationExchange` is designed to facilitate the creation of a Verifiable Presentation by providing tools to select and validate Verifiable Credentials against defined criteria. @@ -84,7 +109,7 @@ const vc = VerifiableCredential.parseJwt(vcJwt) - Select credentials that satisfy a given presentation definition. - Validate if a Verifiable Credential JWT satisfies a Presentation Definition. -- Validate input descriptors within Verifiable Credentials. +- Validate input descriptors within Presentation Definitions. ### Usage @@ -97,10 +122,10 @@ Select Verifiable Credentials that meet the criteria of a given presentation def This returns a list of the vcJwts that are acceptable in the presentation definition. ```javascript -const selectedCredentials = PresentationExchange.selectCredentials( - vcJwts, - presentationDefinition -) +const selectedCredentials = PresentationExchange.selectCredentials({ + vcJwts: signedVcJwts, + presentationDefinition: presentationDefinition +}) ``` ### Satisfying a Presentation Definition @@ -111,13 +136,11 @@ Validate if a Verifiable Credential JWT satisfies the given presentation definit ```javascript try { - PresentationExchange.satisfiesPresentationDefinition(vcJwts, presentationDefinition) + PresentationExchange.satisfiesPresentationDefinition({ vcJwts: signedVcJwts, presentationDefinition: presentationDefinition }) console.log("vcJwts satisfies Presentation Definition!") } catch (e: Error) { console.log("Verification failed: ${e.message}") } - - ``` ### Create Presentation From Credentials @@ -127,26 +150,33 @@ Creates a presentation from a list of Verifiable Credentials that satisfy a give - `presentationDefinition` The Presentation Definition to match against. ```javascript -const presentationResult = PresentationExchange.createPresentationFromCredentials(vcJwts, presentationDefinition) +const presentationResult = PresentationExchange.createPresentationFromCredentials({ vcJwts: signedVcJwts, presentationDefinition: presentationDefinition }) ``` ### Validate Definition This method validates whether an object is usable as a presentation definition or not. +- `presentationDefinition` The Presentation Definition to validate + ```javascript -const valid = PresentationExchange.validateDefinition(presentationDefinition) +const valid = PresentationExchange.validateDefinition({ presentationDefinition }) ``` ### Validate Submission This method validates whether an object is usable as a presentation submission or not. +- `presentationSubmission` The Presentation Submission to validate + ```javascript -const valid = PresentationExchange.validateSubmission(presentationSubmission) +const valid = PresentationExchange.validateSubmission({ presentationSubmission }) ``` ### Validate Presentation Evaluates a presentation against a presentation definition. +- `presentationDefinition` The Presentation Definition to validate +- `presentation` The Presentation + ```javascript -const evaluationResults = PresentationExchange.evaluatePresentation(presentationDefinition, presentation) +const evaluationResults = PresentationExchange.evaluatePresentation({ presentationDefinition, presentation }) ``` \ No newline at end of file diff --git a/packages/credentials/src/presentation-exchange.ts b/packages/credentials/src/presentation-exchange.ts index adb968130..0f4131b52 100644 --- a/packages/credentials/src/presentation-exchange.ts +++ b/packages/credentials/src/presentation-exchange.ts @@ -133,7 +133,9 @@ export class PresentationExchange { * @param {PresentationSubmission} presentationSubmission the object to be validated. * @returns {Validated} the validation results to reveal what is acceptable/unacceptable about the passed object to be considered a valid presentation submission */ - public static validateSubmission(presentationSubmission: PresentationSubmission): Validated { + public static validateSubmission({ presentationSubmission }: { + presentationSubmission: PresentationSubmission + }): Validated { return PEX.validateSubmission(presentationSubmission); } diff --git a/packages/credentials/src/verifiable-credential.ts b/packages/credentials/src/verifiable-credential.ts index 7bd43b1e3..e70a11fca 100644 --- a/packages/credentials/src/verifiable-credential.ts +++ b/packages/credentials/src/verifiable-credential.ts @@ -113,7 +113,7 @@ export class VerifiableCredential { * * @example * ```ts - * const vc = VerifiableCredential.create({ + * const vc = await VerifiableCredential.create({ * type: 'StreetCredibility', * issuer: 'did:ex:issuer', * subject: 'did:ex:subject', @@ -209,7 +209,7 @@ export class VerifiableCredential { * * @example * ```ts - * val vc = VerifiableCredential.parseJwt({ vcJwt: signedVcJwt }) + * const vc = VerifiableCredential.parseJwt({ vcJwt: signedVcJwt }) * ``` * * @param vcJwt The verifiable credential JWT as a [String]. diff --git a/packages/credentials/tests/presentation-exchange.spec.ts b/packages/credentials/tests/presentation-exchange.spec.ts index bf3082239..688b36a4e 100644 --- a/packages/credentials/tests/presentation-exchange.spec.ts +++ b/packages/credentials/tests/presentation-exchange.spec.ts @@ -169,7 +169,9 @@ describe('PresentationExchange', () => { vcJwts: [btcCredentialJwt], presentationDefinition }); - const result = PresentationExchange.validateSubmission(presentationResult.presentationSubmission); + + const presentationSubmission = presentationResult.presentationSubmission; + const result = PresentationExchange.validateSubmission({ presentationSubmission }); expect(result).to.deep.equal([{ tag: 'root', status: 'info', message: 'ok' }]); }); @@ -186,7 +188,8 @@ describe('PresentationExchange', () => { expect(presentationEvaluationResults.errors).to.deep.equal([]); expect(presentationEvaluationResults.warnings).to.deep.equal([]); - const result = PresentationExchange.validateSubmission(presentationResult.presentationSubmission); + const presentationSubmission = presentationResult.presentationSubmission; + const result = PresentationExchange.validateSubmission({ presentationSubmission }); expect(result).to.deep.equal([{ tag: 'root', status: 'info', message: 'ok' }]); });