update readme

TBD54566975 · Nov 7, 2023 · 50be4bd · 50be4bd
1 parent 23429e7
commit 50be4bd
Show file tree

Hide file tree

Showing 2 changed files with 160 additions and 42 deletions.
diff --git a/packages/credentials/README.md b/packages/credentials/README.md
@@ -1,51 +1,162 @@
-## Credentials
+# Credentials
 
+The Credentials package enables the creation, signing, verification, and general processing of `Verifiable Credentials` (VCs). It also has full `Presentation Exchange` support.
 
-### VerifiableCredential Creation and Verification
+## Verifiable Credential
 
-The `VerifiableCredential` class provides methods for the creation, handling, and signing of Verifiable Credentials (VCs) in JWT format.
-- **VerifiableCredential.create**: Creates a Verifiable Credential (VC) in JWT format.
-- **VerifiableCredential.validatePayload**: Validates the structure and integrity of a Verifiable Credential payload.
-- **VerifiableCredential.verify**: Verifies the integrity of a VC JWT.
-- **VerifiableCredential.decode**: Decodes a VC JWT into its constituent parts: header, payload, and signature.
+### Features
 
-### VP Creation and Verification
+- 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.
 
-The `VerifiablePresentation` class provides utility methods for creation and handling Verifiable Presentations (VPs) in JWT format.
-- **VerifiablePresentation.create**: Creates a Verifiable Presentation (VP) in JWT format from a presentation definition and set of credentials.
-- **VerifiablePresentation.verify**: Verifies the integrity of a VP JWT.
-- **VerifiablePresentation.validatePayload**: Validates the structure and integrity of a Verifiable Presentation payload.
-- **VerifiablePresentation.decode**: Decodes a VP JWT into its constituent parts: header, payload, and signature.
+### Usage:
+### Creating a Verifiable Credential
 
-### Presentation Exchange Helpers
+Create a new `VerifiableCredential` with the following parameters:
 
-These methods assist in evaluating verifiable credentials and presentations against specified presentation definitions.
+- `type`: Type of the credential.
+- `issuer`: Issuer URI.
+- `subject`: Subject URI.
+- `data`: Credential data.
+- `expirationDate?`: (optinal) Expiration Date
 
-- **VerifiableCredential.evaluateCredentials**: Evaluates a set of verifiable credentials against a specified presentation definition.
-- **VerifiablePresentation.evaluatePresentation**: Evaluates a given Verifiable Presentation against a specified presentation definition.
+```javascript
+class StreetCredibility {
+  constructor(localRespect, legit) {
+    this.localRespect = localRespect;
+    this.legit = legit;
+  }
+}
 
-### Verifiable Credentials and Presentations Library
-Note: you do not have to use the functions to create SSI objects, you can instead create them yourselves with the boilerplate types in types.ts
+const vc = new VerifiableCredential({
+  type: "StreetCred",
+  issuer: "did:example:issuer",
+  subject: "did:example:subject",
+  data: new StreetCredibility("high", true)
+});
+```
+
+### Signing a Verifiable Credential
+Sign a `VerifiableCredential` with a DID:
+
+- `signOptions`: The sign options used to sign the credential.
+
+First create a SignOptions object as follows:
+```javascript
+import { Ed25519, Jose } from '@web5/crypto';
+import { DidKeyMethod } from '@web5/dids';
+
+const issuer = await DidKeyMethod.create();
+const privateKey = (await Jose.jwkToKey({ key: issuer.keySet.verificationMethodKeys![0].privateKeyJwk! })).keyMaterial;
+
+const signOptions = {
+  issuerDid: issuer.did,
+  subjectDid: "did:example:subject",
+  kid: `${issuer.did}#${issuer.did.split(':')[2]}`,
+  signer: async (data) => await Ed25519.sign({ data, key: privateKey })
+};
+```
+
+Then sign the VC using the signoptions object
+```javascript
+const vcJwt = vc.sign(signOptions)
+```
+
+### Verifying a Verifiable Credential
+Verify the integrity and authenticity of a VC JWT
 
-```typescript
-      const vc: VerifiableCredentialV1 = {
-        '@context'          : ['https://www.w3.org/2018/credentials/v1'],
-        'id'                : 'my-cred',
-        'type'              : ['VerifiableCredential'],
-        'issuer'            : 'did:key:123',
-        'issuanceDate'      : getCurrentXmlSchema112Timestamp(),
-        'credentialSubject' : {
-          'btcAddress': 'btcAddress123'
-        }
-      };
+- `vcJwt`: The VC in JWT format as a String.
+```javascript
+try {
+  await VerifiableCredential.verify(vcJwt)
+  console.log("VC Verification successful!")
+} catch (e: Error) {
+  console.log("VC Verification failed: ${e.message}")
+}
 ```
-### Signer Options Object
 
-The `Signer` represents a function that takes a byte array as input and returns a promise that resolves to a byte array, representing the signature of the input data.
+### Parsing a JWT into a Verifiable Credential
+Parse a JWT into a `VerifiableCredential` instance
 
-### Type Definition
+`vcJwt`: The VC JWT as a String.
 
-```typescript
-type Signer = (data: Uint8Array) => Promise<Uint8Array>;
+```javascript
+const vc = VerifiableCredential.parseJwt(vcJwt)
 ```
 
+## Presentation Exchange
+
+`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.
+
+
+### Usage
+
+### Selecting Credentials
+Select Verifiable Credentials that meet the criteria of a given presentation definition.
+
+- `vcJwts`: The list of Verifiable Credentials to select from.
+- `presentationDefinition` The Presentation Definition to match against.
+
+This returns a list of the vcJwts that are acceptable in the presentation definition.
+```javascript
+const selectedCredentials = PresentationExchange.selectCredentials(
+    vcJwts,
+    presentationDefinition
+)
+```
+
+### Satisfying a Presentation Definition
+Validate if a Verifiable Credential JWT satisfies the given presentation definition. Will return an error if the evaluation results in warnings or errors.
+
+- `vcJwts`: The list of Verifiable Credentials to select from.
+- `presentationDefinition` The Presentation Definition to match against.
+
+```javascript 
+try {
+  PresentationExchange.satisfiesPresentationDefinition(vcJwts, presentationDefinition)
+  console.log("vcJwts satisfies Presentation Definition!")
+} catch (e: Error) {
+  console.log("Verification failed: ${e.message}")
+}
+
+
+```
+
+### Create Presentation From Credentials
+Creates a presentation from a list of Verifiable Credentials that satisfy a given presentation definition. This function initializes the Presentation Exchange (PEX) process, validates the presentation definition, evaluates the credentials against the definition, and finally constructs the presentation result if the evaluation is successful.
+
+- `vcJwts`: The list of Verifiable Credentials to select from.
+- `presentationDefinition` The Presentation Definition to match against.
+
+```javascript
+const presentationResult = PresentationExchange.createPresentationFromCredentials(vcJwts, presentationDefinition)
+```
+
+### Validate Definition
+This method validates whether an object is usable as a presentation definition or not.
+
+```javascript
+const valid = PresentationExchange.validateDefinition(presentationDefinition)
+```
+
+### Validate Submission
+This method validates whether an object is usable as a presentation submission or not.
+
+```javascript
+const valid = PresentationExchange.validateSubmission(presentationSubmission)
+```
+
+### Validate Presentation
+Evaluates a presentation against a presentation definition.
+
+```javascript
+const evaluationResults = PresentationExchange.evaluatePresentation(presentationDefinition, presentation)
+```
diff --git a/packages/credentials/src/presentation-exchange.ts b/packages/credentials/src/presentation-exchange.ts
@@ -20,9 +20,9 @@ export class PresentationExchange {
   /**
    * Selects credentials that satisfy a given presentation definition.
    *
-   * @param vcJwts The list of Verifiable Credentials to select from.
-   * @param presentationDefinition The Presentation Definition to match against.
-   * @return A list of Verifiable Credentials that satisfy the Presentation Definition.
+   * @param {string[]} vcJwts The list of Verifiable Credentials to select from.
+   * @param {PresentationDefinitionV2} presentationDefinition The Presentation Definition to match against.
+   * @return {string[]} selectedVcJwts A list of Verifiable Credentials that satisfy the Presentation Definition.
    */
   public static selectCredentials(
     vcJwts: string[],
@@ -33,6 +33,13 @@ export class PresentationExchange {
     return selectResults.verifiableCredential as string[] ?? [];
   }
 
+  /**
+   * Validates if a list of VC JWTs satisfies the given presentation definition.
+   *
+   * @param {string[]} vcJwts An array of VC JWTs as strings.
+   * @param {PresentationDefinitionV2} presentationDefinition The criteria to validate against.
+   * @throws {Error} If the evaluation results in warnings or errors.
+   */
   public static satisfiesPresentationDefinition(
     vcJwts: string[],
     presentationDefinition: PresentationDefinitionV2
@@ -109,9 +116,9 @@ export class PresentationExchange {
   /**
    * This method validates whether an object is usable as a presentation definition or not.
    *
-   * @param presentationDefinition: presentationDefinition to be validated.
+   * @param {PresentationDefinitionV2} presentationDefinition: presentationDefinition to be validated.
    *
-   * @return the validation results to reveal what is acceptable/unacceptable about the passed object to be considered a valid presentation definition
+   * @return {Validated} the validation results to reveal what is acceptable/unacceptable about the passed object to be considered a valid presentation definition
    */
   public static validateDefinition(presentationDefinition: PresentationDefinitionV2): Validated {
     return PEX.validateDefinition(presentationDefinition);
@@ -120,9 +127,9 @@ export class PresentationExchange {
   /**
    * This method validates whether an object is usable as a presentation submission or not.
    *
-   * @param presentationSubmission the object to be validated.
+   * @param {PresentationSubmission} presentationSubmission the object to be validated.
    *
-   * @return the validation results to reveal what is acceptable/unacceptable about the passed object to be considered a valid presentation submission
+   * @return {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 {
     return PEX.validateSubmission(presentationSubmission);