Update @web5/credentials README (#349)

* update readme * updates * Update packages/credentials/README.md Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/README.md Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/README.md Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/README.md Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/README.md Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/tests/presentation-exchange.spec.ts Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * Update packages/credentials/tests/presentation-exchange.spec.ts Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> * minor readme updates --------- Co-authored-by: Frank Hinek <frankhinek@users.noreply.github.com> Co-authored-by: Moe Jangda <moe@tbd.email>
TBD54566975 · Dec 13, 2023 · edc8054 · edc8054
1 parent 05ff2ab
commit edc8054
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 32 deletions.
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
@@ -1,17 +1,40 @@
-# Credentials
+# `@web5/credentials` <!-- omit in toc -->
 
-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 <!-- omit in toc -->
 
-### 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,23 +67,25 @@ 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();
 ```
 
 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,18 +98,18 @@ 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.
 
 ### Features
 
 - 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 })
 ```
diff --git 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
@@ -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
@@ -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' }]);
     });